Skip to content
ilinxa/pro-ui

Media Carousel

alphav0.4.0

Embla image and video carousel — gallery or linear variants, coordinated video pause for inactive slides.

Category: MediaUpdated: 2026-10-29Created: 2026-05-02Author: ilinxa

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

Initialize shadcn (once per project)Seeds lib/utils.ts and components.json. Skip if you've already used any shadcn component.
pnpm dlx shadcn@latest init
Install the component
pnpm dlx shadcn@latest add @ilinxa/media-carousel

Add -fixtures for dummy data:

pnpm dlx shadcn@latest add @ilinxa/media-carousel-fixtures

CLI 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

Demo source

demo.tsxtsx
"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&apos;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&apos;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&apos;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., &quot;jump to media that has the comment user mentioned&quot;).        </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=&quot;natural-clamped&quot;</code> (frame from the          first item&apos;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=&quot;rtl&quot;</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=&quot;tr&quot;</code> with Turkish function-form labels and the counter chip.          Inspect the slides: <code>aria-label=&quot;Slayt 1 / 3&quot;</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&apos;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          &mdash; 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=&quot;4:5&quot;</code> and <code>aspect=&quot;1.91:1&quot;</code>: any{" "}          <code>&quot;W:H&quot;</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.20.3
labels.slideAriaLabel / goToSlide as stringsFunctions (n, total) => string / (n) => string; strings still work (deprecated)
rtldir="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 squareHonours aspect
DEFAULT_MEDIA_CAROUSEL_LABELSdefaultMediaCarouselLabels (old name kept, deprecated)

Anti-patterns

  • Don't add extra fields to MediaItem — strict discriminated union. Custom shapes go via renderItem with TS intersection.
  • Don't expect virtualization — kasder posts ≤10 media; lazyVideoDistance is 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-strip variant in v0.1 — deferred (no concrete consumer in this scope; story-rail uses raw Embla).
  • Don't pass inline objects to labels: bust React.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 via labels.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 ancestor dir — 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

Tags

media-carouselcarouselmediaemblagallery

Dependencies

shadcn primitives: button
npm peer deps: embla-carousel@^8.6.0, embla-carousel-react@^8.6.0, lucide-react@^1.11.0
internal: video-player, expandable-text