@rozie-ui/embla-react

Idiomatic react Carousel — a cross-framework carousel compiled from one Rozie source wrapping Embla Carousel (v8). The current snap is two-way bound via selectedIndex; slides come as a slides config array or as default-slot DOM. This package is generated; do not edit src/ by hand.

Declarative-mode slides must carry class="rozie-embla__slide". The component pins Embla's slides option to that exact selector, so unclassed default-slot children are not measured as slides.

Install

npm i @rozie-ui/embla-react

Peer dependencies: the embla-carousel (^8.6) + embla-carousel-autoplay (^8.6) engine packages + react + react-dom. Install them alongside this package.

No engine CSS to import — the carousel skeleton styles (overflow: hidden viewport, flex container, slide sizing) ship scoped inside the component.

Usage

import { useState } from 'react';
import { Carousel } from '@rozie-ui/embla-react';

export function Demo() {
  const [index, setIndex] = useState(0);
  return (
    <Carousel
      slides={['A', 'B', 'C']}
      selectedIndex={index}
      onSelectedIndexChange={setIndex}
      loop
      onSelect={(i) => console.log('snap', i)}
    />
  );
}

Props

| Name | Type | Default | Two-way (model) | Required | | --- | --- | --- | :---: | :---: | | slides | Array | [] | | | | loop | Boolean | false | | | | align | String | "center" | | | | axis | String | "x" | | | | slidesToScroll | Number | 1 | | | | dragFree | Boolean | false | | | | draggable | Boolean | true | | | | containScroll | String | "trimSnaps" | | | | startIndex | Number | 0 | | | | skipSnaps | Boolean | false | | | | duration | Number | 25 | | | | direction | String | "ltr" | | | | autoplay | Boolean | false | | | | autoplayDelay | Number | 4000 | | | | dots | Boolean | false | | | | arrows | Boolean | false | | | | thumbnails | Boolean | false | | | | plugins | Array | [] | | | | options | Object | {} | | | | selectedIndex | Number | 0 | ✓ | |

Events

| Event | Payload | Description | | --- | --- | --- | | select | index: number | Fires on every snap change (drag, scroll, or programmatic). Distinct from the selectedIndex model prop — a model prop must not share a name with an emit. | | settle | — | Fires when carousel motion stops (after a drag, scroll, or reInit settles). | | reInit | — | Fires when the engine re-initialises (an option flip, a slide add/remove, or a manual reInitCarousel() call). The current snap is preserved across it. | | pointer-down | — | Fires when a pointer drag begins on the viewport. |

Imperative handle

Beyond props, the component exposes imperative methods (declared once in the Rozie source via $expose). Grab a handle with the native ref mechanism and call them directly:

import { useRef } from 'react';
import { Carousel, type CarouselHandle } from '@rozie-ui/embla-react';

const carousel = useRef<CarouselHandle>(null);
// <Carousel ref={carousel} ... />
carousel.current?.scrollNext();
const i = carousel.current?.getSelectedIndex();

| Method | Description | | --- | --- | | scrollNext | Scroll to the next snap — scrollNext(jump?) (jump skips the transition). No-op before mount. | | scrollPrev | Scroll to the previous snap — scrollPrev(jump?). No-op before mount. | | scrollToIndex | Scroll to a specific snap index — scrollToIndex(index, jump?) (Embla scrollTo). Named to avoid the inherited DOM HTMLElement.scrollTo(x, y). No-op before mount. | | reInitCarousel | Re-initialise the Embla engine (recompute snaps) — reInitCarousel(opts?). Pass raw EmblaOptionsType to override; omit to re-apply the current prop-derived options. (NOT reInit, which is the emitted event.) | | canScrollNext | Return whether a next snap is reachable — canScrollNext(). False before mount. | | canScrollPrev | Return whether a previous snap is reachable — canScrollPrev(). False before mount. | | getSelectedIndex | Return the current scroll-snap index — getSelectedIndex() (Embla selectedScrollSnap()). 0 before mount. (NOT selectedIndex, which is the two-way model prop.) | | scrollSnapList | Return the snap-point progress array — scrollSnapList() (numbers in [0, 1]). Empty before mount. | | scrollProgress | Return the overall scroll progress in [0, 1] — scrollProgress() — to drive a custom progress bar / scrollbar thumb. 0 before mount. | | slidesInView | Return the indices of slides currently in view — slidesInView() — for lazy-loading or highlighting in-view dots. Empty before mount. | | slidesNotInView | Return the indices of slides currently out of view — slidesNotInView() — to unload heavy off-screen content. Empty before mount. | | previousScrollSnap | Return the previously selected snap index — previousScrollSnap() — to compute transition direction. 0 before mount. | | getPlugins | Return the live plugin API map — getPlugins() (e.g. getPlugins().autoplay?.play()/.stop()) for imperative autoplay pause/resume. (NOT plugins, which is a prop.) Null before mount. | | getInstance | Return the underlying EmblaCarouselType instance for direct API access (the engine escape hatch). Null before mount. |

Slots

| Slot | Params | | --- | --- | | slide | slide, index | | (default) | | | thumb | slide, index |