Media Carousel

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, 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 })
  }
/>

Localized labels

const TR_LABELS = {
  carouselLabel: "Medya galerisi",
  previousSlide: "Önceki",
  nextSlide: "Sonraki",
  goToSlide: "Slayta git",
  slideAriaLabel: "Slayt {index} / {total}",
} as const;

<MediaCarousel items={items} variant="gallery" labels={TR_LABELS} />

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; v0.2 candidate (lazyVideoDistance) 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" (template 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: pass rtl={true} — Embla handles drag direction; chevrons flip via rtl:rotate-180.