Media Carousel
alphav0.4.0Embla image and video carousel — gallery or linear variants, coordinated video pause for inactive slides.
Context
Use anywhere a swipeable strip of mixed images + videos is needed — Instagram-style post media (gallery), product galleries (linear), event photo strips, news article photo sets, real estate listings. The 'gallery' variant matches kasder's Instagram-post peek-scale-blur aesthetic exactly: focused image at center is full-bleed sharp; neighbors are scaled to 95%, opacity-60, and 1px-blurred (the blur is a CSS variable; 0px matches a no-blur prototype). Soft edge gradients (background → transparent, 12 rem each side) further soften peek edges. The 'linear' variant is full-width snap (no peek, no scale). Single-item posts bypass the carousel entirely (no nav, no indicators, no scale). Built-in image + video handlers; renderItem slot for full per-slide takeover. **First cross-folder import in pro-ui's registry** — composes video-player directly for the built-in video handler. shadcn registryDependencies handles install. Migration origin: kasder kas-social-front-v0 PostMediaCarousel.tsx; third ship in the 8-component social-posts-system arc.
Installation
pnpm dlx shadcn@latest initpnpm dlx shadcn@latest add @ilinxa/media-carouselAdd -fixtures for dummy data:
pnpm dlx shadcn@latest add @ilinxa/media-carousel-fixturesCLI can't resolve @ilinxa? The namespace is listed in the official shadcn registry directory, so current CLIs need no configuration. If yours can't resolve it (older or pinned versions, self-hosted mirrors), register it manually in components.json:
"registries": {
"@ilinxa": "https://ui.ilinxa.com/r/{name}.json"
}Preview

Instagram-style peek-scale gallery. Double-tap any slide → console log. The video at index 3 auto-pauses when you swipe to other slides — that's the isActive contract from video-player.
Demo source
"use client"; import { useRef, useState, type CSSProperties } from "react";import { Button } from "@/components/ui/button";import { Tabs, TabsContent, TabsTrigger } from "@/components/ui/tabs";import { SwipeTabsList } from "@/components/site/swipe-tabs-list";import { MediaCarousel } from "./media-carousel";import { DUMMY_MIXED_MEDIA, DUMMY_PRODUCT_PHOTOS, DUMMY_SINGLE_IMAGE, DUMMY_SINGLE_VIDEO, arLabels, captionedItems, errorRefreshItems, mixedRatioItems, prototypeItems, refreshedImageUrl, trLabels, twoItems, videoItems,} from "./dummy-data";import type { MediaCarouselHandle } from "./types"; function ImperativeRefDemo() { const ref = useRef<MediaCarouselHandle>(null); const [currentIdx, setCurrentIdx] = useState(0); return ( <div className="space-y-3"> <MediaCarousel ref={ref} items={DUMMY_MIXED_MEDIA} variant="gallery" onSlideChange={(idx) => setCurrentIdx(idx)} /> <div className="flex flex-wrap items-center gap-2"> <span className="text-xs text-muted-foreground"> Active: <span className="font-mono">{currentIdx + 1}</span> /{" "} {DUMMY_MIXED_MEDIA.length} </span> <Button type="button" size="sm" variant="outline" onClick={() => ref.current?.scrollPrev()} > Prev </Button> <Button type="button" size="sm" variant="outline" onClick={() => ref.current?.scrollNext()} > Next </Button> <Button type="button" size="sm" variant="outline" onClick={() => ref.current?.scrollTo(0)} > Jump to 1 </Button> <Button type="button" size="sm" variant="outline" onClick={() => ref.current?.scrollTo(2)} > Jump to 3 (video) </Button> </div> </div> );} const PROTOTYPE_STYLE = { "--media-carousel-inactive-blur": "0px",} as CSSProperties; function ControlledDemo() { const [index, setIndex] = useState(0); const [locked, setLocked] = useState(false); const last = prototypeItems.length - 1; const go = (next: number) => setIndex(Math.min(last, Math.max(0, next))); return ( <div className="space-y-3"> <MediaCarousel items={prototypeItems} variant="gallery" loop={false} index={index} onIndexChange={(next) => { if (!locked) setIndex(next); }} /> <div className="flex flex-wrap items-center gap-2"> <span className="text-xs text-muted-foreground"> index = <span className="font-mono">{index}</span> </span> <Button type="button" size="sm" variant="outline" onClick={() => go(index - 1)}> Prev </Button> <Button type="button" size="sm" variant="outline" onClick={() => go(index + 1)}> Next </Button> <Button type="button" size="sm" variant={locked ? "default" : "outline"} aria-pressed={locked} onClick={() => setLocked((v) => !v)} > {locked ? "Locked (not adopting)" : "Lock"} </Button> </div> <p className="text-xs text-muted-foreground"> <code>index</code> + <code>onIndexChange</code> held in state: the prop wins on every render. Turn on <strong>Lock</strong> and swipe — the parent ignores the change, so the carousel settles back to the held index. External Prev / Next always work. </p> </div> );} function ErrorRefreshDemo() { const [log, setLog] = useState<string[]>([]); return ( <div className="space-y-3"> <MediaCarousel items={errorRefreshItems} variant="linear" aspect="natural-clamped" onMediaError={async (item) => { setLog((l) => [...l, `onMediaError(${item.id}) called`]); await new Promise((r) => setTimeout(r, 800)); setLog((l) => [...l, `resolved a fresh URL for ${item.id}`]); return refreshedImageUrl; }} /> <div className="rounded-md border border-border bg-muted p-3 font-mono text-xs" aria-live="polite"> {log.length === 0 ? ( <span className="text-muted-foreground">No calls yet.</span> ) : ( log.map((line, i) => <div key={i}>{line}</div>) )} </div> <p className="text-xs text-muted-foreground"> Slide 1's <code>url</code> is dead (<code>/__missing__/expired.jpg</code>).{" "} <code>onMediaError</code> fires once, resolves a new URL after 800 ms, and the image is retried with it. A second failure for the same item would not call again. </p> </div> );} export default function MediaCarouselDemo() { return ( <Tabs defaultValue="gallery"> <SwipeTabsList> <TabsTrigger value="gallery">Gallery (mixed)</TabsTrigger> <TabsTrigger value="linear">Linear (photos)</TabsTrigger> <TabsTrigger value="single">Single-item shortcut</TabsTrigger> <TabsTrigger value="custom">Custom renderItem</TabsTrigger> <TabsTrigger value="imperative">Imperative ref</TabsTrigger> <TabsTrigger value="prototype">Prototype</TabsTrigger> <TabsTrigger value="rtl">RTL</TabsTrigger> <TabsTrigger value="tr">Turkish</TabsTrigger> <TabsTrigger value="controlled">Controlled</TabsTrigger> <TabsTrigger value="error">Error refresh</TabsTrigger> <TabsTrigger value="video">Video</TabsTrigger> <TabsTrigger value="captions">Captions</TabsTrigger> <TabsTrigger value="two">Two items</TabsTrigger> <TabsTrigger value="ratios">4:5 / 1.91:1</TabsTrigger> </SwipeTabsList> <TabsContent value="gallery" className="mt-6 space-y-3"> <MediaCarousel items={DUMMY_MIXED_MEDIA} variant="gallery" onDoubleTap={(item, idx) => console.log("[demo] double-tap", item.id, idx) } /> <p className="text-xs text-muted-foreground"> Instagram-style peek-scale gallery. Double-tap any slide → console log. The video at index 3 auto-pauses when you swipe to other slides — that's the <code>isActive</code> contract from{" "} <code>video-player</code>. </p> </TabsContent> <TabsContent value="linear" className="mt-6 space-y-3"> <MediaCarousel items={DUMMY_PRODUCT_PHOTOS} variant="linear" aspect="video" loop={false} /> <p className="text-xs text-muted-foreground"> Linear snap variant — full-width slides, no peek, no loop. Default for product galleries / photo sets where each slide is independent. </p> </TabsContent> <TabsContent value="single" className="mt-6 space-y-6"> <div className="space-y-2"> <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground"> Single image (no nav, no indicators, no scale) </p> <MediaCarousel items={DUMMY_SINGLE_IMAGE} variant="gallery" onDoubleTap={(item) => console.log("[demo] single tap", item.id)} /> </div> <div className="space-y-2"> <p className="text-xs font-medium uppercase tracking-wide text-muted-foreground"> Single video (no nav, no indicators, no scale) </p> <MediaCarousel items={DUMMY_SINGLE_VIDEO} variant="gallery" /> </div> </TabsContent> <TabsContent value="custom" className="mt-6 space-y-3"> <MediaCarousel items={DUMMY_MIXED_MEDIA} variant="gallery" renderItem={(item, ctx) => ( <div className="relative h-full w-full"> {item.type === "image" ? ( <> <img src={item.url} alt={item.alt ?? ""} loading="lazy" className="h-full w-full object-cover" /> <div className="absolute right-2 bottom-2 rounded-full bg-foreground/70 px-2 py-0.5 font-mono text-xs text-background tabular-nums"> {ctx.index + 1} / {DUMMY_MIXED_MEDIA.length} </div> </> ) : ( <div className="flex h-full w-full items-center justify-center bg-muted"> <span className="text-xs text-muted-foreground"> [video item: custom render not implemented] </span> </div> )} </div> )} /> <p className="text-xs text-muted-foreground"> The <code>renderItem</code> slot replaces both built-in handlers. Here we draw a slide-counter overlay on each image. Video items fall to the consumer's placeholder (in real apps, wire your own video player here). </p> </TabsContent> <TabsContent value="imperative" className="mt-6"> <ImperativeRefDemo /> <p className="mt-3 text-xs text-muted-foreground"> Imperative ref handle: <code>scrollTo(idx)</code> /{" "} <code>scrollPrev()</code> / <code>scrollNext()</code> /{" "} <code>getCurrentIndex()</code>. Use for programmatic navigation (e.g., "jump to media that has the comment user mentioned"). </p> </TabsContent> <TabsContent value="prototype" className="mt-6 space-y-3"> <div className="mx-auto max-w-md" style={PROTOTYPE_STYLE}> <MediaCarousel items={prototypeItems} variant="gallery" showCounter showNavButtons="fine-pointer" aspect="natural-clamped" /> </div> <p className="text-xs text-muted-foreground"> The platform post carousel: <code>aspect="natural-clamped"</code> (frame from the first item's 3:2, mixed sizes after it), counter chip, nav buttons only under a mouse, and <code>--media-carousel-inactive-blur: 0px</code> set through a style object on a wrapper. </p> </TabsContent> <TabsContent value="rtl" className="mt-6 space-y-3"> <div dir="rtl" lang="ar" className="rounded-xl border border-border bg-card p-4"> <MediaCarousel items={mixedRatioItems} variant="gallery" showCounter locale="ar" labels={arLabels} /> </div> <p className="text-xs text-muted-foreground"> No <code>dir</code> prop: the direction comes from the ancestor <code>dir="rtl"</code>. Slides lay out right-to-left, <kbd>←</kbd> goes to the next slide, chevrons and nav buttons swap sides, and the counter and labels use Arabic (function-form <code>slideAriaLabel</code>,{" "} <code>goToSlide</code>, <code>counter</code>). </p> </TabsContent> <TabsContent value="tr" className="mt-6 space-y-3"> <MediaCarousel items={mixedRatioItems} variant="linear" aspect="natural-clamped" showCounter locale="tr" labels={trLabels} /> <p className="text-xs text-muted-foreground"> <code>locale="tr"</code> with Turkish function-form labels and the counter chip. Inspect the slides: <code>aria-label="Slayt 1 / 3"</code>, dots{" "} <code>1. slayta git</code>. </p> </TabsContent> <TabsContent value="controlled" className="mt-6"> <ControlledDemo /> </TabsContent> <TabsContent value="error" className="mt-6"> <ErrorRefreshDemo /> </TabsContent> <TabsContent value="video" className="mt-6 space-y-3"> <MediaCarousel items={videoItems} variant="gallery" aspect="video" showCounter /> <p className="text-xs text-muted-foreground"> Two videos (poster before play) and an image. Only the active slide's video can play, and the active video pauses when the carousel is scrolled out of view (below ~50 % visible) — start one, then scroll the page. </p> </TabsContent> <TabsContent value="captions" className="mt-6 space-y-3"> <MediaCarousel items={captionedItems} variant="gallery" aspect="4:5" showCounter /> <p className="text-xs text-muted-foreground"> <code>caption</code> sits under the frame, inside the slide: it is read once with its slide, clamped to <code>captionLines</code> (2) with a Show more toggle. The middle item has no caption and takes no space (the carousel height follows the active slide); the dots move below the slides while any caption exists. </p> </TabsContent> <TabsContent value="two" className="mt-6 space-y-3"> <MediaCarousel items={twoItems} variant="gallery" showCounter /> <p className="text-xs text-muted-foreground"> Two items in a gallery: Embla cannot fill a loop with them, so the carousel is not looping — the first and last slides get the edge margin and Prev / Next are disabled at the ends. The counter chip sits inside the active frame, never over the neighbour. </p> </TabsContent> <TabsContent value="ratios" className="mt-6 space-y-6"> <MediaCarousel items={captionedItems} variant="linear" aspect="4:5" /> <MediaCarousel items={captionedItems} variant="linear" aspect="1.91:1" /> <p className="text-xs text-muted-foreground"> <code>aspect="4:5"</code> and <code>aspect="1.91:1"</code>: any{" "} <code>"W:H"</code>, the same strings media-editor and carousel-composer use. </p> </TabsContent> </Tabs> );} Usage
When to use
Anywhere a swipeable horizontal strip of mixed images + videos is needed — Instagram-style post media (gallery), product galleries (linear), event photo strips, news article photo sets, real estate listings. The galleryvariant matches kasder's Instagram-post peek-scale aesthetic; the linear variant is full-width snap. Single-item posts bypass the carousel entirely (no nav, no indicators, no scale). Built-in image + video handlers; renderItem slot for full per-slide takeover.
Basic example
import { MediaCarousel } from "@/components/media-carousel";
export function PostMedia({ post }: { post: Post }) {
return <MediaCarousel items={post.media} variant="gallery" />;
}Linear variant (product gallery)
<MediaCarousel
items={product.photos}
variant="linear"
aspect="video"
loop={false}
/>Cross-folder import: video items get full video-player
The built-in video item handler imports video-player directly. shadcn registryDependencies ensures both install when you run pnpm dlx shadcn@latest add @ilinxa/media-carousel. Videos in inactive slides pause cleanly via the isActive contract — no consumer wiring needed.
Custom renderItem slot
Replaces both built-in handlers. Receives (item, { isActive, inView, index }) — consumer renders whatever (HLS player, 360° viewer, branded controls).
<MediaCarousel
items={items}
variant="gallery"
renderItem={(item, { isActive, index }) =>
item.type === "panorama" ? (
<PanoramaViewer src={item.url} active={isActive} />
) : (
<DefaultRenderer item={item} isActive={isActive} />
)
}
/>Imperative ref handle
const carouselRef = useRef<MediaCarouselHandle>(null);
<MediaCarousel ref={carouselRef} items={items} variant="gallery" />
<button onClick={() => carouselRef.current?.scrollTo(2)}>
Jump to slide 3
</button>Double-tap-to-like integration
Unified onDoubleTap(item, index) fires for both image and video items. Use to trigger heart-burst overlays (composes with engagement-bar's EngagementHeartBurst sub-export) or analytics.
<MediaCarousel
items={post.media}
variant="gallery"
onDoubleTap={(item, idx) => {
setBurstKey((k) => k + 1);
onLike(post.id);
analytics.track("post.double_tap", { id: post.id, idx });
}}
/>onSlideChange for analytics
Fires only on Embla's selectevent (post-snap, not during drag). Mount-sync does NOT fire — first-render is silent so analytics consumers don't track a phantom "view slide 0" on every page load.
<MediaCarousel
items={post.media}
variant="gallery"
onSlideChange={(idx) =>
analytics.track("post.slide", { id: post.id, idx })
}
/>Captions and any aspect
A caption on an item shows under its frame, inside its slide (read once with it), clamped to captionLines (default 2) with a Show more. The carousel takes the active slide's height, so an item without a caption takes no space. aspect also takes any "W:H"; labels.video and locale reach every video, and a video item's alt names it.
<MediaCarousel
items={[
{ id: "a", type: "image", url: "/a.jpg", alt: "Harbour at dusk", caption: "First evening" },
{ id: "b", type: "video", url: "/b.mp4", alt: "Ferry crossing" },
]}
variant="gallery"
aspect="4:5"
labels={{ captionShowMore: "Devamı", captionShowLess: "Daha az", video: { play: "Oynat" } }}
locale="tr"
/>Natural-clamped aspect + dimensions
Give image and video items their intrinsic width / height (plus optional srcSet / sizes on images). The frame is reserved before load, and aspect="natural-clamped" uses the first item's ratio clamped to [minRatio, maxRatio] (default 4/5 to 1.91): 3:4 becomes 4:5, 16:9 stays, 3:1 becomes 1.91:1. Without dimensions the loaded natural size is used (one layout change). aspect applies to both variants and to a single item; in a gallery every slide shares the first item's frame. A video's width / height only feed the frame ratio.
<MediaCarousel
items={[
{ id: "a", type: "image", url, alt: "Forest", width: 600, height: 800 },
{ id: "b", type: "video", url: mp4, poster, width: 1280, height: 720 },
]}
variant="gallery"
aspect="natural-clamped"
minRatio={4 / 5}
maxRatio={1.91}
/>Labels: function forms
slideAriaLabel(position, total), goToSlide(position) and counter(position, total, format) take functions (positions are 1-based; format renders a number in locale). New text labels: carouselRoleDescription, slideRoleDescription. The 0.2 string forms ("Slide {index} of {total}", "Go to slide") are deprecated but still accepted. An undefined value keeps the default. Hoist the object to module scope.
const TR_LABELS: MediaCarouselLabels = {
carouselLabel: "Medya galerisi",
previousSlide: "Önceki slayt",
nextSlide: "Sonraki slayt",
goToSlide: (n) => `${n}. slayta git`,
slideAriaLabel: (n, total) => `Slayt ${n} / ${total}`,
counter: (n, total, format) => `${format(n)}/${format(total)}`,
carouselRoleDescription: "galeri",
slideRoleDescription: "slayt",
};
<MediaCarousel items={items} variant="gallery" labels={TR_LABELS} />Locale + counter
showCounter adds a "2/5" chip (default off) built by labels.counter. locale (BCP 47, default "en"; an invalid tag falls back to "en") formats its numbers, e.g. Arabic-Indic digits for "ar".
<MediaCarousel items={items} variant="gallery" showCounter locale="ar" labels={AR_LABELS} />Direction
By default the direction is read from the element after mount, so an ancestor dir="rtl" is enough. Pass dir="ltr" | "rtl" to force it. Embla, arrow keys, chevrons, nav-button sides, peek margins and edge fades all follow the one resolved value. rtl is a deprecated alias, honoured only when set (rtl={false} still forces LTR).
<div dir="rtl" lang="ar">
<MediaCarousel items={items} variant="gallery" locale="ar" labels={AR_LABELS} />
</div>
// or explicitly
<MediaCarousel items={items} variant="linear" dir="rtl" />Controlled index
Pass index + onIndexChange to control the slide: the prop wins on every render, so a swipe calls back and the carousel settles back to the held index unless the parent adopts the change (the snap-back runs after the drag settles, never mid-drag). index without onIndexChange is read-only. onIndexChange is silent for the settle-back and for prop-driven scrolls. Uncontrolled: defaultIndex sets the start. onSlideChange keeps firing as before.
const [index, setIndex] = useState(0);
<MediaCarousel items={items} variant="gallery" index={index} onIndexChange={setIndex} />
<button onClick={() => setIndex((i) => Math.max(0, i - 1))}>Prev</button>Refreshing expired media: onMediaError
Called when a built-in image or video fails to load (expired signed URL and the like). Resolve a new URL string to retry once with it; a second failure for the same item does not call again, and a new url from the host resets the item. A recovered image drops its srcSet / sizes; a video shows its loading state meanwhile and resumes at the same time and play state. Not called for renderItem slides.
<MediaCarousel
items={post.media}
variant="gallery"
onMediaError={async (item) => {
const { url } = await api.refreshMediaUrl(item.id);
return url; // retried once
}}
/>Nav buttons on fine pointers
showNavButtons is true by default; "fine-pointer" renders the side buttons only under (pointer: fine) (mouse / trackpad), resolved after mount, so touch devices swipe without them.
<MediaCarousel items={items} variant="gallery" showNavButtons="fine-pointer" />CSS variables
--media-carousel-fade sets the edge-fade colour (default var(--background)); --media-carousel-inactive-blur sets the blur of inactive gallery slides (default 1px). Set them through className or on any ancestor. The platform post prototype is the defaults plus --media-carousel-inactive-blur: 0px.
<div style={{ "--media-carousel-inactive-blur": "0px" } as React.CSSProperties}>
<MediaCarousel items={items} variant="gallery" showCounter aspect="natural-clamped" />
</div>
// or via a class
<MediaCarousel className="[--media-carousel-fade:var(--card)]" items={items} variant="gallery" />Video: in-view pausing and RenderItemContext.inView
Built-in video slides show their poster before play, never autoplay, and play only when the slide is active and the carousel is at least ~50 % in the viewport: scroll the post away and the playing video pauses. isActive still means "the centred slide" (a half-scrolled post does not dim its active slide); the separate inView field is true on the server and on first render. A custom video in renderItem should play on isActive && inView.
<MediaCarousel
items={items}
variant="gallery"
renderItem={(item, { isActive, inView, index }) =>
item.type === "video" ? (
<MyPlayer src={item.url} playing={isActive && inView} />
) : (
<img src={item.url} alt={item.alt ?? ""} />
)
}
/>Upgrading from 0.2
| 0.2 | 0.3 |
|---|---|
labels.slideAriaLabel / goToSlide as strings | Functions (n, total) => string / (n) => string; strings still work (deprecated) |
rtl | dir="rtl" or an ancestor dir; rtl deprecated |
aspect ignored by variant="gallery" | aspect applies to the gallery too (default stays square): a host passing both sees the frame change |
Single item in linear always square | Honours aspect |
DEFAULT_MEDIA_CAROUSEL_LABELS | defaultMediaCarouselLabels (old name kept, deprecated) |
Anti-patterns
- Don't add extra fields to
MediaItem— strict discriminated union. Custom shapes go viarenderItemwith TS intersection. - Don't expect virtualization — kasder posts ≤10 media;
lazyVideoDistanceis not implemented (possible future addition) for larger sets. - Don't expect a fullscreen lightbox on slide-click — separate UX (would be
image-lightbox-01). - Don't expect
feature-stripvariant in v0.1 — deferred (no concrete consumer in this scope; story-rail uses raw Embla). - Don't pass inline objects to
labels: bustReact.memo. Hoist to module scope.
Accessibility
- Carousel root:
role="region"+aria-roledescription="carousel"per WAI-ARIA APG. - Each slide:
role="group"+aria-roledescription="slide"+aria-label="Slide N of M"(function configurable vialabels.slideAriaLabel). - Indicator dots get
aria-current="true"when active. - Embla provides arrow-key keyboard nav natively when the viewport has focus.
- RTL: set
dir="rtl"or an ancestordir— Embla direction, arrow keys, chevrons and nav sides follow it.
Features
- Two variants — gallery (Instagram peek-scale-blur) + linear (full-width snap)
- Gallery layout — slides 1 − 2 × peekRatio wide (85% by default) with the neighbours peeking; first/last edge peek (logical margins) whenever Embla is not looping (also when it drops the loop because the slides can't fill it)
- Inactive slide visuals — 95% scale, 60% opacity, `--media-carousel-inactive-blur` (default 1px; set 0px for no blur); transitions gated by motion-safe
- Edge fades (gallery) — logical start/end, colour from `--media-carousel-fade` (default the background token)
- Aspect — square / video / portrait / auto / natural-clamped (first item's ratio clamped to minRatio 4:5 … maxRatio 1.91:1) / any "W:H" such as "4:5" or "1.91:1", for both variants and a single item
- Per-slide caption — under the frame, inside its slide (read once with it), clamped to captionLines (default 2) with a localized Show more; the carousel takes the active slide's height, so an item without a caption takes no space
- Item dimensions — width / height reserve the frame; srcSet / sizes / decoding=async on the built-in <img>
- onMediaError — an expired image or video URL asks the host once for a replacement and retries
- Built-in video slides via <VideoPlayer> — poster before play; only the active slide plays, and it pauses while the carousel is less than half in view (IntersectionObserver); labels.video + locale reach every player, a video item's alt names it
- renderItem slot for full per-slide takeover; context carries isActive, inView, index
- Controlled index (opt-in) — index + onIndexChange, the prop wins every render (a swipe settles back unless adopted); defaultIndex when uncontrolled
- Direction — dir prop or the element's direction after mount; Embla, arrow keys, chevrons, nav sides, peek and fades agree (rtl kept as a deprecated alias)
- Click a peeking neighbour to scroll to it; inactive slides stay out of the tab order and the accessibility tree
- showNavButtons: true / false / "fine-pointer" (mouse and trackpad only)
- Counter chip (showCounter) with locale-formatted numbers, inside the active slide's frame
- Typed labels — function forms for slide names, dot names and the counter; role descriptions; the 0.2 string templates still accepted
- Single-item shortcut — bypasses Embla entirely for items.length === 1
- Indicator dots — bottom-center, 16px active pill, click-to-jump, aria-current
- Imperative ref handle — scrollTo / scrollPrev / scrollNext / getCurrentIndex (stable identity)
- Unified onDoubleTap(item, index) for both image + video items
- onSlideChange fires on Embla 'select' (mount-sync silent)
- WAI-ARIA APG carousel pattern — region / slide groups / aria-current; ArrowLeft/Right (direction-aware), Home/End


