GSCarousel

A dependency-free, feature-rich carousel/slider available in two flavours from one codebase:

• Native / vanilla JS — a window.GSCarousel(selector, params) factory plus a window.GSCarouselConfigue instance registry.
• React — a <GSCarousel /> component with an imperative ref handle.

Both share the exact same engine (actions/, constants/, helpers/, types/), so behaviour is identical across the two.

Features

• 25 transition types — from plain classic scroll to cinematic kenBurns, 3D coverflow3d / cube / cylinder3d / flip, and filter-driven liquid / sand / glassFade melts.
• Multiple slides per view (slidesToShow / slidesToScroll).
• Infinite loop with automatic cloning.
• autoplay with pause-on-hover / pause-on-focus / pause-on-indicators-hover, a one-time autoplayStart delay, and an optional autoplayProgress bar.
• Drag / swipe (mouse + touch).
• Responsive breakpoints.
• Arrows — built-in (with 5 visual styles + tunable size), by selector, or your own element.
• Indicators / dots — 11 dot styles (default, linear, snake, progress, pill, capsule, glowpill, gravity, chain, satellite, skipstone), row/column, overlay, optional chrome strip, external container.
• Slide counter with templating.
• Opt-in liquid-glass UI — iOS-style glass on the arrows / overlay indicators / overlay counter. Chromium gets a real SVG refraction (displacement + chromatic aberration); Safari/Firefox fall back to a frosted backdrop blur. Tunable distortion, blur, tint, opacity, saturation, radius; works with any type.
• Opt-in kenBurns slow zoom/pan on the active image, caption scrim styling for .gs-caption children, and parallaxContent for .gs-parallax-bg layers — all work with any transition type.
• Theming — light / dark / auto (follows OS) plus a custom accent color token.
• Adaptive height, vertical mode, variable size, RTL, reverse ping-pong.
• syncWith to pair two carousels (e.g. main + thumbnails); a built-in gallery type does the same with an auto-generated thumbnail strip.
• Keyboard accessibility, lifecycle hooks (beforeInit, afterInit, beforeChange, afterChange) + gesture/edge/breakpoint/destroy callbacks.
• Loading skeleton that waits for images.

Installation

npm i @get-set/gs-carousel

Compatibility

| Target | Requirement | |---|---| | React (the <GSCarousel> component) | React 16.8+ (Hooks are required), and 17 / 18 / 19. React is an optional peer dependency — you only need it for the component. | | Native / vanilla (window.GSCarousel) | No framework. Any modern evergreen browser. | | TypeScript | First-class — type declarations (.d.ts) ship in the package. | | SSR / Next.js | Safe to import server-side (no DOM access at module load). The carousel itself is browser-only, so render it inside a Client Component ('use client'). |

Verified on React 18 (including StrictMode) and Next.js 14 (App Router). The peer range is ^16.8.0 || ^17.0 || ^18.0 || ^19.0, with react/react-dom marked optional so the native build has zero peer dependencies.

Package entry points

From package.json:

| Field | Value | |---|---| | name | @get-set/gs-carousel | | main | dist/components/GSCarousel.js | | module | dist/components/GSCarousel.js | | types | dist/components/GSCarousel.d.ts | | exports['.'].import | ./dist/components/GSCarousel.js (React/ESM) | | exports['.'].require | ./dist-js/bundle.js (native UMD bundle) | | files | dist, dist-js, styles, example.html |

Project layout

GSCarousel.ts             # native entry  (webpack -> dist-js/bundle.js, window global)
components/GSCarousel.tsx  # React component (tsc -> dist/, npm entry)
actions/                  # shared engine
constants/                # shared constants
helpers/uihelpers.ts      # shared helpers
types/                    # Params / Ref / Window augmentation
components/styles/         # SCSS + compiled CSS + CSS-as-TS (runtime injection for React)
styles/                   # SCSS + compiled CSS (for <link> use by the native build)

Build

npm install
npm run build          # builds both targets
npm run build:js       # native bundle -> dist-js/bundle.js
npm run build:react    # React + types  -> dist/

Tests

Unit tests use Vitest + jsdom:

npm test         # run once
npm run test:watch

Coverage spans the pure logic (param resolution, breakpoints, validation, helpers), DOM behaviour (registry, clones, arrows, indicators, counter, ignoreItems, destroy/re-init), the React component (structure, prop-stripping, disabled, mount/unmount lifecycle), and regression tests for every fixed bug. Note: jsdom has no layout engine, so pixel-level translate/sizing is validated separately via in-browser testing rather than units.

Usage — Native JS

The markup must follow this structure:

<link rel="stylesheet" href="styles/GSCarousel.css" />

<div class="my-carousel">
  <div class="gs-list-container">
    <div class="gs-list">
      <div class="gs-item"><img src="1.jpg" /></div>
      <div class="gs-item"><img src="2.jpg" /></div>
      <div class="gs-item"><img src="3.jpg" /></div>
    </div>
  </div>
</div>

<script src="dist-js/bundle.js"></script>
<script>
  new GSCarousel('.my-carousel', {
    type: 'withScale',
    slidesToShow: 5,
    loop: true,
    arrows: true,
    autoplay: true
  });
</script>

GSCarousel is exposed as a global factory. You can call it with a CSS selector string or a real element:

new GSCarousel('.my-carousel', { slidesToShow: 3 });
new GSCarousel(document.querySelector('.my-carousel'), { slidesToShow: 3 });

The bundle also registers a jQuery plugin and an HTMLElement.prototype adapter — both create the carousel exactly like the factory and register it in window.GSCarouselConfigue:

// jQuery (when jQuery is present on the page)
$('.my-carousel').GSCarousel({ slidesToShow: 3, loop: true });

// HTMLElement.prototype
document.querySelector('.my-carousel').GSCarousel({ slidesToShow: 3 });

window.GSCarousel(...) accepts a selector or a real element, so the jQuery / prototype adapters (which pass the element) work the same. (detect() / detectAll() prototype helpers are also present for internal use.)

The instance registry — window.GSCarouselConfigue

Every carousel registers itself in window.GSCarouselConfigue.references under its reference key. Look up a live instance and call its imperative methods:

new GSCarousel('.my-carousel', { reference: 'main' });

const instance = window.GSCarouselConfigue.instance('main');
instance.next();        // advance
instance.goTo(2);       // jump to slide index 2
instance.refresh();     // full rebuild (re-resolve params + re-render)
instance.destroy();     // tear down (clears timers, observers, clones, listeners)

window.GSCarouselConfigue shape:

| Member | Type | Description | |---|---|---| | references | Array<{ key: string; ref: Ref }> | All registered instances. | | instance(key) | (key: string) => Ref \| undefined | Look up an instance's runtime Ref by its reference key. |

Usage — React

import GSCarousel from '@get-set/gs-carousel';

export default function Gallery() {
  return (
    <GSCarousel
      type="withScale"
      slidesToShow={5}
      loop
      arrows
      autoplay
      // Tune the coverflow falloff (optional). Defaults: focused 1, min 0.6, minOpacity 0.4.
      scale={{ focused: 1, min: 0.6, minOpacity: 0.4 }}
    >
      <img src="1.jpg" />
      <img src="2.jpg" />
      <img src="3.jpg" />
    </GSCarousel>
  );
}

Each direct child is wrapped in a .gs-item automatically. Styles are injected at runtime — no CSS import required.

Next.js (App Router)

The carousel is browser-only, so use it from a Client Component:

'use client';
import GSCarousel from '@get-set/gs-carousel';

export default function Gallery() {
  return (
    <GSCarousel type="withScale" slidesToShow={5} loop arrows>
      <img src="/1.jpg" />
      <img src="/2.jpg" />
      <img src="/3.jpg" />
    </GSCarousel>
  );
}

The gsx prop (React only)

gsx injects scoped inline styles for a single instance — a recursive CSS map keyed by selectors, scoped to this carousel via its data-key. Use it to theme one instance without a stylesheet:

<GSCarousel
  type="classic"
  gsx={{
    '.gs-item': { borderRadius: '12px' },
    '.gs-arrow': { background: 'rebeccapurple' }
  }}
>
  {/* … */}
</GSCarousel>

Options

Covers every field of Params. All are optional.

| Option | Type | Default | Description | |---|---|---|---| | reference | string | random GUID | Unique key (used by syncWith and the registry). | | referance | string | – | Deprecated misspelled alias of reference. | | className | string | – | Extra class on the carousel root. | | type | CarouselType (see catalog) | 'classic' | Transition mode. | | slidesToShow | number | 1 | Slides visible at once. | | slidesToScroll | number | 1 | Slides advanced per step. | | initialSlide | number | 0 | 0-based slide the carousel starts on. | | loop | boolean | true | Infinite looping (adds clones). | | activeIndex | number | 1 | 1-based slot (within the visible window) that holds the active item; the track repositions so the active item lands there. For withScale it's the zoomed slot. Overrides centerMode. | | centerMode | boolean | false | Shortcut for "active item centered" (activeIndex = middle slot). Ignored if activeIndex is set. | | edgeBlankSpace | boolean | false | Non-loop only: true lets the first/last item reach the active slot leaving blank space at the edge; false clamps so no blank shows. | | scale | { focused?, min?, minOpacity? } | { focused: 1, min: 0.6, minOpacity: 0.4 } | withScale / coverflow3d / fan: focused = scale of the zoomed item, min = scale of the farthest side item, minOpacity = its opacity. Side items interpolate. | | coverflow | { perspective?, rotate?, depth? } | { perspective: 1000, rotate: 50, depth: 100 } | coverflow3d only: 3D tuning — perspective (px), max rotate (deg) and depth (translateZ px) of the farthest side card. | | cube | { perspective? } | { perspective: 1000 } | cube only: perspective (px) of the cube viewport. | | accordionCollapsedSize | string \| number | '60px' | accordion only: flex-basis of a collapsed panel (CSS length or px number). | | stackPeek | number | 2 | stack (and tinder layout) only: how many cards peek behind the top card. | | stackOffset | number | 14 | stack (and tinder layout) only: px offset between stacked cards. | | stackScaleStep | number | 0.06 | stack (and tinder layout) only: scale reduction per depth. | | fan | { rotate?, arc?, originY? } | { rotate: 22, arc: 24, originY: '160%' } | fan only: max splay rotate (deg) and arc (px) of side cards, and the pivot originY. | | cylinder | { perspective?, faces? } | { perspective: 1200, faces: derived } | cylinder3d only: viewport perspective (px) and number of faces around the ring (min 3). | | fade | { zoom?, direction? } | { zoom: 1.12, direction: 'center' } | fade only: cinematic cross-fade zoom and pan direction (center / edges / corners). | | wipe | { direction? } | { direction: 'left' } | wipe only: reveal edge — left / right / up / down. | | iris | { origin? } | { origin: 'center' } | iris only: growth point of the circular reveal — center / corner. | | curtain | { direction? } | { direction: 'horizontal' } | curtain only: split axis — horizontal (left/right) or vertical (top/bottom). | | parallax | { depth?, layerSelector? } | { depth: 0.3, layerSelector: '.gs-parallax-bg' } | parallax type only: depth (0..1 drift fraction) and the bg layer selector. | | spotlight | { brightness?, blur?, minOpacity? } | { brightness: 0.45, blur: 3, minOpacity: 1 } | spotlight only: brightness / max blur (px) / opacity of the farthest side item (focused stays sharp). | | wheel | { radius?, arc? } | { radius: derived, arc: 360 } | wheel only: ring radius (px) and total angular arc (deg) the items occupy. | | tinder | { threshold?, rotation?, maxRotate? } | { threshold: 0.35, rotation: 0.06, maxRotate: 18 } | tinder only: throw threshold (fraction of width), rotation (deg per px of drag), maxRotate (deg cap). | | gallery | { position?, thumbSize?, thumbGap?, renderThumb? } | { position: 'bottom', thumbSize: 72, thumbGap: 8 } | gallery only: thumbnail-strip position (top/bottom/left/right), thumbSize (px), thumbGap (px), and a renderThumb(slide, index) builder. | | glassFade | { distortion?, blur?, chromatic? } | { distortion: 180, blur: 14, chromatic: 0 } | glassFade only: refraction strength, edge blur (px), and chromatic-aberration spread (px; 0 = cheap single pass). | | liquid | { distortion?, blur?, frequency?, flow? } | { distortion: 130, blur: 8, frequency: 16, flow: 40 } | liquid only: melt displacement, peak blur (px), blob scale, and flow distance (px). | | sand | { erode?, grain?, drift? } | { erode: 0.7, grain: 130, drift: 22 } | sand only: peak erosion (0..1), grain fineness, and drift jitter (px). | | marqueeSpeed | number | 60 | marquee only: continuous scroll speed (px/sec). | | marqueeDirection | 'left' \| 'right' | 'left' | marquee only: scroll direction. | | marqueeBounce | boolean | false | marquee only: ping-pong between edges instead of an infinite loop. | | glass | boolean \| GlassOptions | false | Opt-in liquid-glass treatment for the floating UI (arrows / overlay indicators / overlay counter). true for defaults, or an object to tune (see catalog). Works with any type. | | arrowStyle | 'default' \| 'circle' \| 'square' \| 'minimal' \| 'outline' \| 'floating' | 'default' | Visual style of the built-in nav arrows. Ignored for external (user-supplied) arrows. | | arrowSize | number | – | Pixel size of the built-in arrow buttons (sets --gs-arrow-size). | | caption | boolean \| CaptionOptions | false | Opt-in styled scrim/reveal for .gs-caption children. true for defaults, or an object (position, scrim, animate). | | kenBurns | boolean \| KenBurnsOptions | false | Opt-in slow zoom/pan on the active image slide. Works with any type. true for defaults, or an object (zoom, direction, amount, duration). | | parallaxContent | boolean | false | Apply .gs-parallax-bg layer parallax on translate-driven types (classic / withScale / coverflow3d / fan / spotlight / gallery). Uses the parallax tuning. | | autoplayProgress | boolean | false | Show a bar that fills across each autoplay interval. No effect unless autoplay is on. | | theme | 'light' \| 'dark' \| 'auto' | – | Color theme for the chrome (arrows / indicators / counter / captions). auto follows the OS. | | accent | string | – | Accent color for indicators / progress / controls (sets --gs-accent). Any CSS color. | | autoplay | boolean | true | Auto-advance. | | autoplaySpeed | number | 3000 | Delay between auto-advances (ms). | | autoplayStart | number | 0 | One-time delay (ms) before the first auto-advance; later advances use autoplaySpeed. | | animationSpeed | number | 1000 | Transition duration (ms). | | arrows | boolean | true | Show prev/next arrows. | | prevArrow / nextArrow | string \| HTMLElement | built-in buttons | Markup string, CSS selector, or element. | | draggable | boolean | true | Mouse/touch dragging. | | indicators | boolean \| IndicatorsParams | false | Dots config (type, direction, overlay, positions, containerStyle, indicatorsContainer, …). | | indicatorsContainer | string \| HTMLElement | – | Render indicators into this element (top-level shortcut for indicators.indicatorsContainer; the nested value wins if both are set). | | counter | boolean \| CounterParams \| string | false | Slide counter (template, positions, overlay, class). A bare string is treated as the template. | | adaptiveHeight | boolean | false | Match container height to the visible slide(s). | | vertical | boolean | false | Vertical orientation. | | variableSize | boolean | false | Slides keep their natural size. | | gap | string \| number \| null | – | Gap between slides. | | previewPercent | number | 0 | Peek amount of adjacent slides. | | showPreview | boolean | – | Enable the adjacent-slide preview. | | focusOnSelect | boolean | true | Click a slide to navigate to it. | | ignoreItems | string | .gs-ignore | Selector for elements in the track to exclude from the carousel (hidden, not counted/cloned). | | focusedZoomedIndex | number | – | Deprecated — use activeIndex/centerMode. 0 maps to centerMode:true; any other value maps to activeIndex. | | reverse | boolean | false | Auto ping-pong direction. | | rightToLeft | boolean | false | RTL autoplay direction. | | rigthToLeft | boolean | false | Deprecated misspelled alias of rightToLeft. | | pauseOnHover / pauseOnFocus | boolean | true | Pause autoplay on interaction. | | accessibility | boolean | true | Arrow-key navigation + focus handling. | | syncWith | string | – | reference of another carousel to keep in sync (linked bidirectionally). | | responsive | Array<{ windowSize, params }> | [] | Per-breakpoint overrides (params is a partial of these options). | | disabled | boolean | false | Skip initialisation. | | gsx | NestedCSS | – | React only — scoped inline styles for the instance. |

indicators object (IndicatorsParams)

| Field | Type | Default | Description | |---|---|---|---| | visible | boolean | – | Show the indicators. | | class | string | – | Extra class on the indicators container. | | type | dot style (see catalog) | 'default' | Dot rendering style. | | direction | 'row' \| 'column' | 'row' | Layout axis. | | oneIndicatorVisibility | boolean | – | Keep a single indicator visible even with one page. | | overlay | boolean | false | Float the dots over the carousel. | | pauseOnIndicatorsHover | boolean | – | Pause autoplay while hovering the dots. | | positionInRow | 'left' \| 'center' \| 'right' | – | Horizontal placement. | | positionInColumn | 'top' \| 'center' \| 'bottom' | – | Vertical placement. | | containerStyle | 'none' \| 'solid' \| 'frost' \| 'outline' \| 'floating' | 'none' | Optional chrome strip behind the dots (additive; does not change the dot type). | | indicatorsContainer | string \| HTMLElement | – | Render the dots into an external element. |

counter object (CounterParams)

| Field | Type | Default | Description | |---|---|---|---| | template | string | '{CurrentIndex} / {Count}' (multi-slide: '{FirstIndex} - {SecondIndex} / {Count}') | Counter text with tokens. | | positionInRow | string | 'right' | Horizontal placement (left / center / right). | | positionInColumn | string | 'bottom' | Vertical placement (top / center / bottom). | | overlay | boolean | false | Float the counter over the carousel. | | class | string | – | Extra class on the counter element. |

Template tokens: {CurrentIndex}, {Count}, and (for multi-slide views) {FirstIndex} / {SecondIndex}.

Variant catalogs

type — transition modes (25)

| Value | Description | |---|---| | classic | Standard horizontal/vertical track scroll. | | withScale | Center item zoomed; side items shrink/fade (coverflow falloff via scale). | | coverflow3d | 3D perspective coverflow with rotation + depth (coverflow + scale). | | fan | Hand-of-cards splay around a pivot (fan + scale). | | cylinder3d | 3D turntable ring of faces (cylinder). | | fade | Cross-fade with optional cinematic zoom + pan (fade). | | flip | 3D card flip between slides. | | cube | 3D rotating cube (cube). | | zoom | Active slide zooms in/out on change. | | wipe | Clip-path edge reveal (wipe). | | pageTurn | 3D book page-turn. | | accordion | Expanding/collapsing panels (accordionCollapsedSize). | | stack | Card deck with peeking cards (stackPeek / stackOffset / stackScaleStep). | | marquee | Continuous scroll (marqueeSpeed / marqueeDirection / marqueeBounce). | | parallax | Background-layer depth scroll (parallax). | | gallery | Main carousel + auto-generated synced thumbnail strip (gallery). | | blurFade | Cross-fade that blurs out and back in. | | spotlight | Focus-by-filter — side items dim/blur (spotlight). | | tinder | Swipe-deck — throw the top card away (tinder, reuses stack* layout). | | wheel | In-plane rotating ring of items (wheel). | | iris | Circular clip reveal expanding from center/corner (iris). | | curtain | Split-open reveal along a horizontal/vertical axis (curtain). | | glassFade | Liquid-glass refraction ripple between slides (glassFade). | | liquid | Slide melts into flowing liquid, then reforms (liquid). | | sand | Slide disintegrates into grainy sand, then reassembles (sand). |

fade / flip / cube / cylinder3d / zoom / wipe / pageTurn / accordion / iris / curtain / glassFade / liquid / sand / blurFade are 1-slide-at-a-time; marquee is continuous.

arrowStyle (5 + default)

| Value | Description | |---|---| | default | Legacy dark pill button. | | circle | Round translucent button. | | square | Rounded-square button. | | minimal | Chromeless arrow — just the glyph. | | outline | Bordered, transparent fill. | | floating | Light pill that lifts on hover with a soft shadow. |

indicators.type — dot styles (11)

| Value | Description | |---|---| | default | Standard round dots. | | linear | Thin bar segments. | | snake | A single pill that slides between positions. | | progress | A filling progress track. | | pill | Pill-shaped dots. | | capsule | Elongated capsule dots. | | glowpill | Glowing pill dots. | | gravity | Dots that bunch/spread with a gravity feel. | | chain | Connected chain-link dots. | | satellite | An orbiting active marker. | | skipstone | Skipping-stone ripple animation. |

indicators.containerStyle — dot chrome strip (5)

| Value | Description | |---|---| | none | No extra chrome (default). | | solid | Soft opaque pill behind the dots. | | frost | Translucent blurred (frosted glass) strip. | | outline | Thin bordered, transparent strip. | | floating | Raised pill with a drop shadow. |

theme

light · dark · auto (follows the OS color scheme).

glass object (GlassOptions)

| Field | Type | Default | Description | |---|---|---|---| | target | 'arrows' \| 'indicators' \| 'counter' \| 'all' | 'all' | Which floating UI gets the glass. | | radius | number | 14 | Corner radius (px) of the glass chrome / refraction mask. | | tint | string | '#ffffff' | Tint color of the translucent fill. | | opacity | number | 0.1 | Tint opacity (0..1). | | saturation | number | 1.6 | Backdrop saturation (vibrancy). | | blur | number | 10 | Edge blur (px) / fallback backdrop blur. | | distortionScale | number | -160 | Main refraction strength (negative = lens-in). | | displace | number | 0 | Output blur after displacement. | | brightness | number | 60 | Brightness (%) of the refraction mask's inner panel. | | borderWidth | number | 0.07 | Width factor of the refracting edge. | | redOffset / greenOffset / blueOffset | number | 0 / 10 / 20 | Per-channel extra displacement (chromatic aberration). | | xChannel / yChannel | 'R' \| 'G' \| 'B' | 'R' / 'G' | Displacement channel selectors. | | mixBlendMode | string | 'difference' | Blend mode for the displacement map's gradient. |

kenBurns object (KenBurnsOptions)

| Field | Type | Default | Description | |---|---|---|---| | zoom | number | 1.15 | Peak zoom over the dwell. | | direction | center / top / bottom / left / right / top-left / top-right / bottom-left / bottom-right | 'center' | Pan/drift direction. | | amount | number | 4 | Drift distance (%) toward the direction at peak zoom. | | duration | number | autoplay dwell, else 5000 | Animation duration (ms). |

caption object (CaptionOptions)

| Field | Type | Default | Description | |---|---|---|---| | position | 'bottom' \| 'top' \| 'center' | 'bottom' | Where the caption sits within the slide. | | scrim | boolean | true | Render the gradient scrim behind the caption. | | animate | boolean | true | Slide/fade the caption in when its slide becomes active. |

Events / callbacks

| Callback | Signature | Fires | |---|---|---| | beforeInit | () => void | before initialisation | | afterInit | () => void | after initialisation (and every re-init/refresh) | | beforeChange | (current, next) => boolean \| void | before a slide change — return false to cancel | | afterChange | (current) => void | after a slide change settles | | onSwipe | (dir: 'left'\|'right'\|'up'\|'down') => void | after a drag/swipe commits | | onEdge | (dir: 'start'\|'end') => void | navigation hits the start/end of a non-looping carousel | | onBreakpoint | (windowSize: number) => void | a responsive breakpoint becomes active | | onDestroy | () => void | the instance is permanently destroyed |

Methods (imperative API)

Native: every method lives on the runtime Ref returned by window.GSCarouselConfigue.instance(key). React: the same methods are exposed on the component's ref via GSCarouselHandle.

| Method | Description | |---|---| | goTo(index, dontAnimate?) | Navigate to a 0-based slide index. | | next() / prev() | Advance / rewind by slidesToScroll. | | play() / pause() | Start/resume or pause autoplay. | | currentSlide() | Returns the active 0-based index. | | getOption(key) / setOption(key, value, refresh?) | Read / set an option live (refresh defaults to true). | | setPosition() | Lightweight recalc of size/position — re-aligns to the current slide without rebuilding clones/handlers (use this instead of refresh() for plain resizes). | | showLoader(duration?) | Show the loading skeleton; auto-hides after duration ms if given. | | hideLoader() | Hide the loading skeleton (fades out, then removes). | | refresh() | Full rebuild (re-resolve params + teardown + re-init) — for structural changes (slidesToShow, type, loop, …). | | add(markup, index?) / remove(index) | Add/remove a slide. Native-oriented — in React, drive slides via children instead. (Native Ref only.) | | destroy() | Permanently tear down the instance. |

The React GSCarouselHandle exposes: goTo, next, prev, play, pause, currentSlide, getOption, setOption, setPosition, showLoader, hideLoader, refresh, destroy. (add / remove are native-only — drive slides via children in React.)

Access — Native:

new GSCarousel('.my-carousel', { reference: 'main' });
const c = window.GSCarouselConfigue.instance('main');
c.next();
c.goTo(2);

Access — React (via a ref to the component):

import GSCarousel, { GSCarouselHandle } from '@get-set/gs-carousel';
import { useRef } from 'react';

const ref = useRef<GSCarouselHandle>(null);
// <GSCarousel ref={ref} …>…</GSCarousel>
ref.current?.next();
ref.current?.goTo(2);

Examples

Native — coverflow with glass arrows, dark theme, progress bar

new GSCarousel('.hero', {
  type: 'coverflow3d',
  slidesToShow: 5,
  centerMode: true,
  loop: true,
  autoplay: true,
  autoplayProgress: true,
  theme: 'dark',
  accent: '#ff5a5f',
  arrowStyle: 'floating',
  glass: { target: 'arrows', radius: 18 },
  indicators: { type: 'glowpill', overlay: true, containerStyle: 'frost' }
});

React — gallery (main + thumbnail strip) with captions

import GSCarousel from '@get-set/gs-carousel';

export default function Product() {
  return (
    <GSCarousel
      type="gallery"
      gallery={{ position: 'bottom', thumbSize: 80, thumbGap: 10 }}
      caption
      kenBurns={{ zoom: 1.1, direction: 'top-right' }}
    >
      <figure>
        <img src="/1.jpg" />
        <figcaption className="gs-caption">Sunrise ridge</figcaption>
      </figure>
      <figure>
        <img src="/2.jpg" />
        <figcaption className="gs-caption">Valley fog</figcaption>
      </figure>
    </GSCarousel>
  );
}

React — two synced carousels

<GSCarousel reference="main" type="fade" slidesToShow={1} arrows>
  {/* big slides */}
</GSCarousel>

<GSCarousel reference="thumbs" syncWith="main" slidesToShow={5} focusOnSelect>
  {/* thumbnails */}
</GSCarousel>

License

ISC.