gpuslider: GPU Image & Video Carousel with Shader Effects

gpuslider is a dependency-free JavaScript carousel library for image and video sliders with GPU-rendered shader effects. Slides can stretch, bend, split into color channels, or switch through liquid and glitch transitions.

It keeps real HTML slides on the page and falls back to browser-rendered media when GPU rendering is unavailable. A CDN entry initializes sliders from HTML attributes, and modular JavaScript imports are available for custom projects.

Features

• A 4.7 KB gzipped core with optional plugins.
• 20+ GPU effects driven by motion, position, and pointer input.
• 20+ transitions for stacked slides and multi-pane galleries.
• Mouse dragging, touch swiping, wheel input, and keyboard navigation.
• Horizontal and vertical movement, looping, and free scrolling.
• Optional autoplay, thumbnail navigation, pagination, and lightbox.
• Responsive sizing and spacing through CSS custom properties.
• Loading-screen and adaptive canvas-quality plugins.
• TypeScript declarations and React components for server-rendered pages.
• Reduced-motion behavior and ARIA-aware navigation controls.
• Custom GLSL effects shared by WebGPU and WebGL 2 renderers.

How To Use It

Installation

Load the stylesheet and the module-based auto initializer from a CDN. This initializes elements with data-gs and loads the GPU renderer only when required.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gpuslider@1/dist/style.css">
<script type="module" src="https://cdn.jsdelivr.net/npm/gpuslider@1/dist/auto.js"></script>

Or install the package via npm.

npm install gpuslider

For a lightbox or loading screen, import the extra stylesheet for the feature that is enabled. A standard carousel only needs style.css.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gpuslider@1/dist/lightbox.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/gpuslider@1/dist/loading.css">

Basic Usage

The CDN method accepts slider options as JSON in data-gs. The data-gs-canvas attribute activates the GPU canvas and selects its effects.

<div class="gs" aria-label="Photo gallery"
     data-gs='{"loop":true}'
     data-gs-canvas="stretch waves">
  <div class="gs-track">
    <div class="gs-slide">
      <img class="gs-media" src="photo-1.jpg" alt="Mountain lake">
    </div>
    <div class="gs-slide">
      <img class="gs-media" src="photo-2.jpg" alt="Coastal cliffs">
    </div>
    <div class="gs-slide">
      <img class="gs-media" src="photo-3.jpg" alt="Forest trail">
    </div>
    <div class="gs-slide">
      <img class="gs-media" src="photo-4.jpg" alt="Sunset beach">
    </div>
    <div class="gs-slide">
      <img class="gs-media" src="photo-5.jpg" alt="Desert dunes">
    </div>
  </div>
  <button data-gs-prev aria-label="Previous slide">&#8249;</button>
  <button data-gs-next aria-label="Next slide">&#8250;</button>
  <div data-gs-dots></div>
</div>

Give the slides a defined height or aspect ratio to reserve space before media loading. The number of visible slides and the gap between them come from CSS.

.gs {
  --gs-per-view: 1.2;
  --gs-gap: 12px;
}
.gs-slide { aspect-ratio: 16 / 9; }
@media (min-width: 960px) {
  .gs { --gs-per-view: 3; }
}

Initialize With JavaScript

Use the core entry when you want to import only the features your carousel needs. The canvas plugin accepts an ordered array of shader effects.

import { createSlider } from 'gpuslider';
import { controls, keyboard } from 'gpuslider/plugins';
import { canvas } from 'gpuslider/canvas';
import { stretch, split } from 'gpuslider/effects';
import 'gpuslider/style.css';
const slider = createSlider(document.querySelector('.gs'), {
  loop: true,
  plugins: [
    controls(),
    keyboard(),
    canvas({ effects: [stretch(), split()] })
  ]
});

The gpuslider/full entry includes controls, keyboard and wheel input, autoplay, auto height, and stacked layouts through additional options. For mode: 'stack', place gs-stack on the HTML root before JavaScript loads. Use the stacked markup in the next example.

import { createSlider } from 'gpuslider/full';
import { canvas } from 'gpuslider/canvas';
import { liquid } from 'gpuslider/effects';
import 'gpuslider/style.css';
createSlider(document.querySelector('.gs-stack'), {
  mode: 'stack',
  loop: true,
  autoplay: 4000,
  plugins: [canvas({ effects: [liquid()] })]
});

Create Shader Transitions

Transitions operate on stacked slides. Reserve slide space with CSS or image dimensions before initialization. A stacked slider displays its first slide when JavaScript is disabled; the other slides are not available through native scrolling.

<div class="gs gs-stack" aria-label="Featured photos">
  <div class="gs-track">
    <div class="gs-slide"><img class="gs-media" src="one.jpg" alt="Photo one"></div>
    <div class="gs-slide"><img class="gs-media" src="two.jpg" alt="Photo two"></div>
    <div class="gs-slide"><img class="gs-media" src="three.jpg" alt="Photo three"></div>
  </div>
</div>

For a modular setup, use stack() and a transition such as burn(). A stack fades between slides when no GPU transition is active.

import { createSlider } from 'gpuslider';
import { stack, controls } from 'gpuslider/plugins';
import { canvas } from 'gpuslider/canvas';
import { burn } from 'gpuslider/effects';
import 'gpuslider/style.css';
createSlider(document.querySelector('.gs-stack'), {
  loop: true,
  plugins: [stack(), controls(), canvas({ effects: [burn()] })]
});

Include Video Slides

The canvas handles images and videos. For automatic inline video playback, use muted and playsinline. The videos() plugin starts and stops media as its slide enters or leaves view. This example assumes the video slide is inside the existing .gs-track.

<div class="gs-slide">
  <video class="gs-media" src="demo.mp4" muted playsinline loop preload="none"></video>
</div>

import { createSlider } from 'gpuslider';
import { videos } from 'gpuslider/plugins';
import { canvas } from 'gpuslider/canvas';
import 'gpuslider/style.css';
createSlider(document.querySelector('.gs'), {
  plugins: [videos(), canvas()]
});

Enable a Lightbox

lightbox() opens images when slides are clicked. An image can specify a larger source through data-gs-full, and open(index) also opens the lightbox programmatically.

import { createSlider } from 'gpuslider';
import { canvas } from 'gpuslider/canvas';
import { lightbox } from 'gpuslider/lightbox';
import 'gpuslider/style.css';
import 'gpuslider/lightbox.css';
const slider = createSlider(document.querySelector('.gs'), {
  plugins: [canvas(), lightbox()]
});
slider.plugins.lightbox.open(0);
// Later: slider.plugins.lightbox.close();

React Integration

React projects can import <Slider> and <Slide> from gpuslider/react. The package works with React 18+ and exposes the core slider options and canvas plugins.

import { Slider, Slide } from 'gpuslider/react';
import { controls, stack } from 'gpuslider/plugins';
import { canvas } from 'gpuslider/canvas';
import { liquid } from 'gpuslider/effects';
import 'gpuslider/style.css';
export function Gallery({ photos }) {
  return (
    <Slider
      className="gs-stack"
      loop
      plugins={[controls(), stack(), canvas({ effects: [liquid()] })]}
      aria-label="Photo gallery"
    >
      {photos.map(photo => (
        <Slide key={photo.src}>
          <img className="gs-media" src={photo.src} alt={photo.alt} />
        </Slide>
      ))}
    </Slider>
  );
}

Server Rendering and Plugin Updates

gpuslider/react is a client component entry for Next.js. The server-rendered markup retains native HTML slides. Load the stylesheet during server rendering and reserve slide dimensions with CSS to avoid a layout shift. The plugins prop is read at creation; use remake when a change requires a new plugin configuration.

Core Configuration Options

Additional Options in gpuslider/full and data-gs

These options enable built-in plugins automatically in the full and declarative entries.

Built-in Plugins

Core plugins are imported from gpuslider/plugins. Canvas and lightbox use their own entry points. Plugin parameters are included here as part of the configuration reference.

Plugin Methods and Properties

Canvas Configuration

canvas() selects WebGPU or WebGL 2 automatically. Set layer when a project needs a particular backend. The canvas begins loading on user interaction or when an active effect requires it; eager: true initializes it immediately.

Direct Renderer Imports

gpuslider/gpu exports the WebGPU renderer and its effects. gpuslider/gl exports the WebGL 2 renderer and its effects. Explicit renderer imports do not select a second backend when the chosen one is unavailable. For layout effects, hit() keeps clicking aligned with GPU-drawn slide positions.

import { gl, hit, coverflow } from 'gpuslider/gl';
import { createSlider } from 'gpuslider';
import 'gpuslider/style.css';
const effects = [coverflow()];
createSlider(document.querySelector('.gs'), {
  align: 'center',
  plugins: [gl({ effects }), hit({ effects })]
});

Shader Effects

Effects are imported from gpuslider/effects and passed to the canvas plugin. Each function accepts an optional settings object. Only their public parameter names are included below.

Layout Effects

Layout effects change where the GPU draws each slide. Use padding when cards extend outside their original positions. Hit testing follows the displayed image when the canvas manages a layout effect.

Transition Effects

Transitions apply to stack() and panes() layouts. Individual transitions are imported from gpuslider/effects.

• liquid(), ripple(), glitch(), burn(), pixelate(), swirl().
• lens(), fluted(), warp(), zoom(), mosaic(), blocks().
• fold(), signal(), push(), chroma(), kaleido(), displace().
• datamosh(), wind(), distance(), glyphs(), weave(), lightning().

Transition Helpers

CSS Variables and Public Classes

Set --gs-per-view, --gs-gap, and --gs-focus on .gs. The progress() plugin writes per-slide values during motion, and loading() exposes loading-screen state.

Styling Notes

The canvas reads border-radius and corner-shape from the page. Shader effects apply to images and videos, not text, links, or buttons in .gs-content. For axis: 'y', set an explicit slider height. Reduced-motion preferences make slide moves immediate and disable speed-driven and pointer-driven effects.

HTML Data Attributes

The CDN auto initializer uses these declarative attributes. Controls can sit inside a slider or in another element associated with it through data-gs-for.

Dynamic Sliders and Declarative Events

For dynamically inserted declarative sliders, the auto() function initializes new elements and sliders.get(element) retrieves their instances from gpuslider/auto. The gs:ready DOM event bubbles when the slider is initialized and provides the instance in event.detail.

import { auto, sliders } from 'gpuslider/auto';
document.addEventListener('gs:ready', (event) => {
  console.log('Slider ready:', event.detail);
});
auto();
const instance = sliders.get(document.querySelector('.gs'));

Slider API Methods and Properties

createSlider(element, options) returns the instance. Its first parameter is the slider root element and its second parameter is the core configuration object. These methods and properties apply to the returned slider unless marked as plugin-specific.

slider.on('change', (index, instance) => {
  console.log('Current snap:', index);
});
slider.to(2);
slider.update();

Events

The standard event callback signature is (detail, slider). The wildcard listener receives (eventName, detail, slider). Plugin events fire only when their corresponding features are active.

React Props and Hooks

The React component exposes the core slider options as props. It also has these component-specific props and hooks.

Loading Plugin Options and State

The loading plugin waits for images and the first frame of each video. Import gpuslider/loading.css for its default screen or use a .gs-loading element of your own. screen: false turns off the overlay but retains progress events. A custom screen present in the initial HTML needs a <noscript> fallback to hide it when scripts are disabled. Failed media count toward completion, and loading() starts images marked loading="lazy" immediately. This behavior suits first-screen galleries and full-page sliders.

Extending gpuslider

Custom plugins are functions that receive a slider instance and return an object. They can register event listeners, modify the measured layout, or request additional animation frames. Plugin registration uses plugins during initialization or slider.use(plugin) later.

Plugin View State

A plugin reads view.places[index] for x (pixels), p (relative slide position), share (visible portion), and visible (visibility state).

Custom GPU effects accept params, head, vertex, uv, color, transition, post, place, and animated. The shader hooks have distinct purposes:

Shader Uniforms

The available shader uniforms are uProgress, uVelocity, uPointer, uPointerSpeed, uPointerIn, uTime, uSize, uView, and uQuad. The uv and color hooks can also read uRadius.

Shader Compatibility

The GPU translation supports a restricted GLSL subset. Avoid struct types, GLSL #define, array declarations, out or inout parameters, and partial vector assignments when an effect needs WebGPU rendering. An effect that fails compilation returns the affected slider to HTML media.

Canvas Draw Hook

slider.plugins.canvas.draw(hook) receives (index, quad) before drawing each slide and returns a function that removes the hook. It lets custom code adjust placement, size, visibility, and effects for GPU-drawn slides.

Alternatives & Related Resources

• Touch-enabled Carousel With RGB Split And Liquid Distortion Effects – rgbKineticSlider
• Cool Slideshow JavaScript Library With WebGL Based Effects – GLSlideshow.js
• Fast, Extensible, Touch-enabled Carousel & Slider JS Library – Smooothy
• Native Scroll Carousel Web Component with Drag – Blossom Carousel

FAQs

Q: Why do remote images appear in HTML but not in the GPU effects?

A: Cross-origin images and videos require CORS response headers and a crossorigin attribute on each media element. A media file that the GPU cannot use as a texture can display through the original HTML element.

Q: Why does the first shader effect appear only after I interact with the slider?

A: The canvas normally initializes when the first interaction or motion requires it. Use canvas({ eager: true }) when the gallery must initialize its GPU canvas immediately.

Q: Can a canvas drawing hook move buttons and links inside a slide?

A: No. draw() changes the GPU rendering position, but interactive HTML stays where the page lays it out. Use a layout effect with a matching place() hook and hit() for accurate slide-level hit testing.