Carousel

اسلایدهایی که با کشیدن، کیبورد یا دکمه‌های قبلی/بعدی پیمایش می‌شوند. موتور اسکرول Embla است؛ جهتش (rtl/ltr) هم روی چیدمان بصری و هم روی معنای کلیدهای جهت‌نما اثر می‌گذارد.

این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

نصب

با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.

pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/carousel.json

npx dig-ui@latest add https://design-system-tau-green.vercel.app/r/carousel.json

yarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/carousel.json

bunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/carousel.json

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Reka UI در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Bits UI در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Angular CDK در دست کار است.

استفاده

import {
  Carousel,
  CarouselContent,
  CarouselItem,
  CarouselNext,
  CarouselPrevious,
} from "@/components/ui/carousel"

<Carousel>
  <CarouselContent>
    <CarouselItem>...</CarouselItem>
    <CarouselItem>...</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Reka UI در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Bits UI در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Angular CDK در دست کار است.

ترکیب اجزا

Carousel یک CarouselContext می‌سازد که carouselRef، وضعیت اسکرول (canScrollPrev/canScrollNext) و همان api خام Embla را نگه می‌دارد؛ useCarousel این context را در اختیار می‌گذارد تا بتوانید کنترل سفارشی (نقطه‌های صفحه، شمارندهٔ اسلاید) بسازید. CarouselContent همان ویوپورت overflow-hidden است و CarouselItem هر اسلاید. پراپ opts مستقیم به useEmblaCarousel می‌رود، پس هر گزینهٔ Embla (loop، align، dragFree، startIndex و…) در دسترس است؛ setApi هم نمونهٔ api را برای کنترل بیرونی (مثل دکمهٔ Play/Pause) می‌دهد.

دسترس‌پذیری

ریشهٔ Carousel با role="region" و aria-roledescription="carousel" مشخص می‌شود؛ هر CarouselItem هم role="group" و aria-roledescription="slide" دارد.
کلید جهت‌نمای فیزیکی راست/چپ همیشه به سمت واقعی خودش حرکت می‌کند، نه به معنای منطقی «قبلی/بعدی»؛ یعنی در چیدمان rtl فلش چپ اسلاید بعدی را نشان می‌دهد، دقیقاً مثل رفتار slider.
دکمه‌های CarouselPrevious و CarouselNext یک sr-only دارند («اسلاید قبلی» / «اسلاید بعدی»)؛ اگر آیکون یا متن دیگری جایگزین کردید همین برچسب را نگه دارید.
وقتی اسلاید اول یا آخر نمایش داده می‌شود، دکمهٔ متناظر خودش disabled می‌شود؛ کاربر کیبورد به یک کنترل بی‌اثر نمی‌رسد.
اگر پلاگین autoplay اضافه می‌کنید، حتماً یک دکمهٔ توقف/شروع در کنارش بگذارید؛ حرکت خودکار بدون کنترل برای کاربرانی که با صفحه‌خوان یا حساسیت حرکتی کار می‌کنند مشکل‌ساز است.

مرجع API

Carousel

ویژگی	نوع	پیش‌فرض	توضیح
orientation	"horizontal" \| "vertical"	"horizontal"	محور اسکرول و پیمایش کیبورد.
dir	"rtl" \| "ltr"	"rtl"	جهت خواندن؛ روی direction موتور Embla و جای/آیکون دکمه‌های قبلی و بعدی اثر می‌گذارد.
opts	EmblaOptionsType	—	تنظیمات خام Embla (align، loop، dragFree، startIndex، containScroll و…).
plugins	EmblaPluginType[]	—	پلاگین‌های Embla، مثل Autoplay یا WheelGestures.
setApi	(api: CarouselApi) => void	—	دسترسی به نمونهٔ خام api برای کنترل بیرونی.

CarouselItem

ویژگی	نوع	پیش‌فرض	توضیح
className	string	—	برای عرض/ارتفاع هر اسلاید از basis-* استفاده کنید (مثلاً basis-1/2).

CarouselPrevious / CarouselNext

ویژگی	نوع	پیش‌فرض	توضیح
variant / size	ButtonProps	"outline" / "icon"	چون روی Button ساخته شده، همهٔ پراپ‌های آن را می‌پذیرد.

useCarousel()

ویژگی	نوع	پیش‌فرض	توضیح
api, scrollPrev, scrollNext	CarouselApi, () => void, () => void	—	برای ساخت کنترل سفارشی (نقطه‌های صفحه، شمارنده) داخل فرزندان Carousel.
canScrollPrev / canScrollNext	boolean	—	برای فعال/غیرفعال کردن دکمه‌های سفارشی.

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Reka UI در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Bits UI در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک روی Angular CDK در دست کار است.

نمونه‌ها

Multiple Items

با basis-1/3 روی CarouselItem و opts.align="start"، سه اسلاید هم‌زمان دیده می‌شود.

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

Vertical

orientation="vertical" محور اسکرول را عوض می‌کند؛ کلیدهای بالا/پایین به‌جای راست/چپ کار می‌کنند.

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

LTR Content

برای محتوایی که خودش انگلیسی/لاتین است (مثلاً گالری بین‌المللی)، dir="ltr" هم چیدمان و هم جهت اسکرول Embla و کلیدها را عوض می‌کند.

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

شمارندهٔ اسلاید با setApi

با useState و setApi می‌توانید اندیس اسلاید فعال را بیرون از کامپوننت بخوانید؛ همین الگو پایهٔ ساخت نقطه‌های صفحه (dots) هم هست.

اسلاید ۱ از ۰

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

یک اسلاید (Empty/Edge)

دکمه‌های قبلی و بعدی را پنهان نکنید؛ خودِ Carousel وقتی حرکتی ممکن نیست آن‌ها را بی‌اثر می‌کند. حذف‌کردن، جای دکمه‌ها را در رفت‌وآمدهای بعدی جابه‌جا می‌کند.

تنها اسلاید

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

کدام نمونه برای کدام موقعیت

نمونه	کجا به کار می‌آید
Multiple Items	با basis-1/3 روی CarouselItem و opts.align="start"، سه اسلاید هم‌زمان دیده می‌شود.
Vertical	orientation="vertical" محور اسکرول را عوض می‌کند؛ کلیدهای بالا/پایین به‌جای راست/چپ کار می‌کنند.
LTR Content	برای محتوایی که خودش انگلیسی/لاتین است (مثلاً گالری بین‌المللی)، dir="ltr" هم چیدمان و هم جهت اسکرول Embla و کلیدها را عوض می‌کند.
شمارندهٔ اسلاید با setApi	با useState و setApi می‌توانید اندیس اسلاید فعال را بیرون از کامپوننت بخوانید؛ همین الگو پایهٔ ساخت نقطه‌های صفحه (dots) هم هست.
یک اسلاید (Empty/Edge)	گالری‌ای که موقتاً فقط یک آیتم دارد

دستورالعمل استفاده

دکمه‌های قبلی/بعدی همیشه در کنار اسلایدها

انجام بده

CarouselPrevious و CarouselNext را همیشه بگذارید تا کسی که نمی‌خواهد یا نمی‌تواند بکشد هم بتواند پیمایش کند.

انجام نده

چرخانده‌ای که فقط با کشیدن پیمایش می‌شود، روی دسکتاپ و برای کاربر کیبورد یا موتوری، بخشی از اسلایدها را کاملاً غیرقابل‌دسترس می‌کند.

عرض اسلاید را با basis مشخص کنید، نه اندازهٔ ثابت پیکسلی

انجام بده

با کلاس basis-1/2 یا basis-1/3 روی CarouselItem، تعداد آیتم دیده‌شده نسبت به عرض کانتینر تنظیم می‌شود و در صفحهٔ کوچک هم درست می‌شکند.

انجام نده

عرض ثابت پیکسلی روی خودِ کارت داخل اسلاید، محاسبهٔ اسنپ Embla را با basis پیش‌فرض (تمام‌عرض) هم‌خوان نمی‌کند و اسلایدها نامنظم می‌شوند.