Carousel

Instalacja#

$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/carousel.json

Użycie#

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

<Carousel aria-label="Product screenshots">
  <CarouselContent>
    <CarouselItem>…</CarouselItem>
    <CarouselItem>…</CarouselItem>
    <CarouselItem>…</CarouselItem>
  </CarouselContent>
  <CarouselPrevious />
  <CarouselNext />
</Carousel>

Przyciski „poprzedni” i „następny” znajdują się poza slajdami, 48 px na lewo i na prawo od nich. Zostaw na nie miejsce — albo ustaw je samodzielnie przez className.

Przykłady#

Kilka slajdów naraz#

Szerokość slajdu ustawisz klasą basis-* na CarouselItem. Połącz ją z responsywnymi prefiksami, żeby na szerszych ekranach pokazać więcej slajdów, oraz z opts={{ align: "start" }}, żeby slajdy przyciągały się do krawędzi początkowej.

<Carousel opts={{ align: "start" }}>
  <CarouselContent>
    <CarouselItem className="basis-1/2 sm:basis-1/3">…</CarouselItem>
  </CarouselContent>
</Carousel>

Odstępy#

Slajdy rozdziela padding na CarouselItem i dopasowany do niego ujemny margines na CarouselContent (domyślnie 16 px). Żeby zmienić odstęp, zmień oba: -ml-2 na treści i pl-2 na każdym elemencie.

Pionowa#

orientation="vertical" przewija w osi Y. Nadaj CarouselContent stałą wysokość; przyciski przeniosą się nad i pod slajdy.

Z API#

setApi przekazuje ci instancję Embla. Użyj jej, żeby zbudować licznik slajdów, kropki paginacji albo miniatury i reagować na zdarzenia select.

const [api, setApi] = React.useState<CarouselApi>()

React.useEffect(() => {
  if (!api) return
  const onSelect = () => setCurrent(api.selectedScrollSnap())
  api.on("select", onSelect)
  return () => {
    api.off("select", onSelect)
  }
}, [api])

<Carousel setApi={setApi}>…</Carousel>

Wytyczne#

Kiedy używać#

• Do przeglądania zestawu równorzędnych elementów, gdy wystarczy widzieć kilka naraz: zrzutów ekranu, szablonów, zdjęć produktów, opinii klientów.
• Na urządzeniach dotykowych, na których przesuwanie palcem po zestawie jest naturalne.

Kiedy nie używać#

• Do treści, którą każdy musi zobaczyć. Slajdy po pierwszym rzadko są oglądane — ważne informacje umieść bezpośrednio na stronie.
• Do nawigacji lub porównywania — użyj komponentu Tabs, siatki albo komponentu Table.
• Do pojedynczego obrazu w sekcji hero — po prostu pokaż ten obraz.

Pokaż, że jest więcej#

Pozwól następnemu slajdowi wyglądać zza krawędzi, pokaż licznik albo kropki i zostaw przycisk „poprzedni” wyłączony na pierwszym slajdzie. Nikt nie powinien się zastanawiać, czy jest coś więcej.

Automatyczne przewijanie#

prfct nie przewija slajdów automatycznie. Jeśli dodasz do Embla wtyczkę autoplay, wstrzymuj przewijanie po najechaniu kursorem i przy fokusie, dodaj widoczny przycisk pauzy i w ogóle nie włączaj automatycznego przewijania, gdy ustawione jest prefers-reduced-motion. Treść, która porusza się sama dłużej niż pięć sekund, musi dać się zatrzymać (WCAG 2.2.2).

Dostępność#

Karuzela to region z aria-roledescription="carousel", a każdy slajd to group z aria-roledescription="slide".

• Nazwij karuzelę. Nadaj Carousel atrybut aria-label, który mówi, co pokazują slajdy: „Zrzuty ekranu produktu”.
• Oznacz slajdy pozycją. Nadaj każdemu CarouselItem atrybut aria-label, np. „2 z 5”, żeby użytkownik wiedział, w którym miejscu jest.
• Przyciski mają etykiety. CarouselPrevious i CarouselNext zawierają dla czytników ekranu etykiety „Poprzedni slajd” i „Następny slajd” — tłumaczone przez LocaleProvider — a na krańcach są wyłączone, chyba że karuzela jest zapętlona.
• Tekst na obrazach. Utrzymuj kontrast 4,5:1 dla tekstu na zdjęciach — użyj przyciemniającej nakładki (scrim), jak w przykładach.

Dokumentacja API#

Carousel#

Element główny. Przyjmuje wszystkie propsy div.

CarouselContent#

Przewijana ścieżka. Przyjmuje wszystkie propsy div; jej ujemny margines razem z paddingiem elementów tworzy odstęp.

CarouselItem#

Pojedynczy slajd, domyślnie na pełną szerokość. Ustaw basis-*, żeby pokazać kilka naraz.

CarouselPrevious, CarouselNext#

Przyciski ikonowe w wariancie outline, podłączone do karuzeli. Przyjmują wszystkie propsy Button; domyślny variant to "outline", a size — "icon-sm".

useCarousel#

Zwraca { api, scrollPrev, scrollNext, canScrollPrev, canScrollNext, orientation } do budowania własnych kontrolek wewnątrz Carousel.