# Specimen Carousel (`specimen-carousel`) > An editorial carousel for type, product, or archive specimens with numbered tabs and hard snap motion. - **Docs:** https://www.mellowui.com/components/specimen-carousel - **Markdown:** https://www.mellowui.com/components/specimen-carousel.md - **Registry:** https://www.mellowui.com/r/specimen-carousel.json - **Tool prompt:** https://www.mellowui.com/api/prompt/specimen-carousel - **Categories:** display, interactive, carousel - **Dependencies:** none ## AI prompt Add a SpecimenCarousel component from the mellow library. It renders an editorial carousel with a large specimen stage, numbered tab strip, keyboard arrow navigation, and optional autoplay. Pass items with title, kicker, sample, meta, and description. Key props: items, initialIndex, autoPlay, interval, onIndexChange. ## Install ```bash npx shadcn@latest add https://mellowui.com/r/specimen-carousel.json ``` ## Props | Prop | Type | Default | Description | |---|---|---|---| | `items` | `SpecimenItem[]` | — | Carousel items. Each item supports title, kicker, description, meta, and sample. | | `initialIndex` | `number` | `0` | Initial active item index. | | `autoPlay` | `boolean` | `false` | Automatically advance through items. Disabled when reduced motion is preferred. | | `interval` | `number` | `4200` | Autoplay interval in milliseconds. | | `className` | `string` | — | Additional CSS classes. | | `onIndexChange` | `(index: number) => void` | — | Called whenever the active index changes. | ## Design notes - Client component (`"use client"`) — required for animation and refs. - Uses Mellow design tokens: `--ink`, `--ink-rgb`, `--background`, `--background-rgb`, `--rule`, `--font-sans`, `--font-serif`, `--font-mono`. Tokens auto-flip between light and dark themes — never hardcode colors. - Respects `prefers-reduced-motion: reduce` where applicable. - Self-contained — no shared utilities. Copy-paste, not a package. ## Source ```tsx "use client"; import React, { useEffect, useMemo, useState } from "react"; export interface SpecimenItem { title: string; kicker?: string; description?: string; meta?: string; sample?: string; } export interface SpecimenCarouselProps { items?: SpecimenItem[]; initialIndex?: number; autoPlay?: boolean; interval?: number; className?: string; style?: React.CSSProperties; onIndexChange?: (index: number) => void; } const DEFAULT_ITEMS: SpecimenItem[] = [ { kicker: "Specimen 01", title: "Editorial", sample: "Aa", meta: "72 pt / italic", description: "A slow snap carousel for type samples, product stories, and image-led editorial modules.", }, { kicker: "Specimen 02", title: "Mechanical", sample: "Rr", meta: "Mono rail", description: "Numbered tabs, registration marks, and a hard-set stage keep the motion tactile.", }, { kicker: "Specimen 03", title: "Archive", sample: "Gg", meta: "Folio set", description: "Each panel behaves like a printed card sliding under a loupe, not a generic carousel.", }, ]; function clampIndex(index: number, length: number) { if (length === 0) return 0; return ((index % length) + length) % length; } function usePrefersReducedMotion() { const [reduced, setReduced] = useState(false); useEffect(() => { const media = window.matchMedia("(prefers-reduced-motion: reduce)"); const update = () => setReduced(media.matches); update(); media.addEventListener("change", update); return () => media.removeEventListener("change", update); }, []); return reduced; } export function SpecimenCarousel({ items = DEFAULT_ITEMS, initialIndex = 0, autoPlay = false, interval = 4200, className, style, onIndexChange, }: SpecimenCarouselProps) { const reduced = usePrefersReducedMotion(); const safeItems = items.length > 0 ? items : DEFAULT_ITEMS; const [index, setIndex] = useState(() => clampIndex(initialIndex, safeItems.length)); const active = safeItems[index]; const folio = useMemo(() => String(index + 1).padStart(2, "0"), [index]); const goTo = (nextIndex: number) => { const next = clampIndex(nextIndex, safeItems.length); setIndex(next); onIndexChange?.(next); }; useEffect(() => { setIndex((current) => clampIndex(current, safeItems.length)); }, [safeItems.length]); useEffect(() => { if (!autoPlay || reduced || safeItems.length < 2) return; const id = window.setInterval(() => { setIndex((current) => { const next = clampIndex(current + 1, safeItems.length); onIndexChange?.(next); return next; }); }, interval); return () => window.clearInterval(id); }, [autoPlay, interval, onIndexChange, reduced, safeItems.length]); return (
{ if (event.key === "ArrowRight") goTo(index + 1); if (event.key === "ArrowLeft") goTo(index - 1); }} >

{active.kicker ?? `Specimen ${folio}`}

{active.meta ?? "Folio carousel"}

{active.sample ?? active.title.slice(0, 2)}

{active.title}

{active.description ?? "Use this panel for a type specimen, featured artifact, product detail, or editorial story."}

{safeItems.map((item, itemIndex) => { const activeItem = itemIndex === index; return ( ); })}
); } export default SpecimenCarousel; ``` ## Demo ```tsx "use client"; import React from "react"; import { SpecimenCarousel } from "../mellow/specimen-carousel"; const specimens = [ { kicker: "Typeface / 1896", title: "Mercury", sample: "Mm", meta: "Display italic", description: "High-contrast forms for loud editorial openers, tuned with tight tracking and a heavy folio presence.", }, { kicker: "Archive / Plate 12", title: "Basalt", sample: "Bb", meta: "Industrial serif", description: "Blocky, mineral weight with registration marks and a mechanical slide between specimens.", }, { kicker: "Foundry / Proof", title: "Orchid", sample: "Oo", meta: "Soft grotesk", description: "A warmer card for brand systems that need some softness without losing the print-room character.", }, { kicker: "Index / New", title: "Vellum", sample: "Vv", meta: "Text family", description: "Quiet bookish texture for long-form pages, product notes, and restrained launch narratives.", }, ]; export default function SpecimenCarouselDemo() { return (
); } ```