Scroll Area

Instalacja#

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

Użycie#

import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area"

<ScrollArea className="h-72 w-48 rounded-xl border">
  {/* long content */}
</ScrollArea>

Nadaj obszarowi stałą wysokość (lub szerokość, przy treści poziomej) — przewija się wszystko, co wykracza poza tę ramkę. Samo przewijanie jest natywne: kółko myszy, bezwładność gładzika, dotyk, klawiatura i zakotwiczanie przewijania działają dokładnie tak jak na zwykłym elemencie z overflow: auto.

Przykłady#

Przewijanie poziome#

Treść przewijana w bok musi być szersza niż obszar (w-max na wierszu flex) i potrzebuje poziomego paska przewijania. Dodaj <ScrollBar orientation="horizontal" /> jako element potomny — pionowy pasek jest dołączony zawsze i pojawia się tylko wtedy, gdy treść wykracza poza obszar w pionie.

Obie osie#

Szerokie dane — arkusze kalkulacyjne, osie czasu, duże tabele — mogą przewijać się w obu kierunkach. Przyklejone nagłówki i pierwsze kolumny pomagają zachować orientację; narożnik, w którym spotykają się paski przewijania, pozostaje pusty.

Zanikające krawędzie#

Element główny informuje, gdzie treść wykracza poza obszar, przez atrybuty data-overflow-y-start i data-overflow-y-end (oraz ich odpowiedniki -x-). Wygaszaj krawędź tylko wtedy, gdy w danym kierunku jest więcej treści — to wskazówka, że obszar się przewija, która znika po dotarciu do końca.

<ScrollArea
  className={cn(
    "relative h-72",
    "after:absolute after:inset-x-0 after:bottom-0 after:h-10 after:bg-linear-to-t after:from-card",
    "after:opacity-0 after:transition-opacity data-overflow-y-end:after:opacity-100"
  )}
>

Paski przewijania#

Paski przewijania nakładają się na treść, zamiast zabierać jej miejsce, więc układ nie zmienia się w zależności od platformy. Pozostają ukryte, dopóki nie najedziesz na obszar lub go nie przewiniesz, a potem znikają; suwak ciemnieje po najechaniu i można go przeciągać.

Wytyczne#

Kiedy używać#

• Do ograniczonych obszarów w układzie, które przewijają się niezależnie: menu, paneli bocznych, wątków czatu, list w kartach, kodu.
• Gdy domyślny pasek przewijania platformy nie pasowałby do gęstego interfejsu z własnym motywem — zwłaszcza grube, zawsze widoczne paski w Windowsie.

Kiedy nie używać#

• Do przewijania całej strony. Pozwól dokumentowi przewijać się natywnie; zagnieżdżone przewijanie głównej treści zmusza do walki z dwiema pozycjami przewijania naraz.
• Do ukrywania treści, która się nie mieści. Jeśli trzeba przewijać małe pole, żeby znaleźć coś ważnego, daj mu więcej miejsca.
• Do poziomego przewijania głównej treści na komputerach. Użytkownicy przeoczają treść wykraczającą w bok; lepiej ją zawijaj lub podziel na strony.

Pokaż, że obszar się przewija#

Nakładane paski przewijania są w spoczynku ukryte, więc to sam obszar musi sugerować, że kryje więcej treści. Przetnij treść przy krawędzi w połowie elementu, wygaś krawędź, za którą jest więcej treści, albo pokaż licznik.

Jeden kierunek naraz#

Trzymaj się jednej osi przewijania w każdym obszarze. Przewijanie w dwóch osiach sprawdza się w siatkach danych, gdzie użytkownicy się go spodziewają; gdzie indziej łatwo się w treści zgubić.

Dostępność#

• Przewijanie klawiaturą. Viewport trafia do kolejności tabulacji tylko wtedy, gdy jego treść wykracza poza obszar. Gdy ma fokus, ↑ ↓ ← →, Page Up, Page Down, Home, End i Spacja przewijają go natywnie, a wewnętrzny pierścień fokusu o grubości 2 px pokazuje, gdzie jesteś.
• Nazwij obszar. Przewijany obszar, który może otrzymać fokus, ale nie ma nazwy, zostanie odczytany jako nic konkretnego. Gdy treść ma znaczenie sama w sobie, umieść ją w punkcie orientacyjnym z etykietą (<section aria-label="Release history">) albo nadaj jej widoczny nagłówek.
• Paski przewijania to udogodnienie dla wskaźnika. Użytkownicy czytników ekranu i klawiatury przewijają viewport bezpośrednio; własne paski przewijania są — tak jak natywne — ukryte przed technologiami wspomagającymi.
• Ograniczony ruch. Przy prefers-reduced-motion paski przewijania pojawiają się i znikają natychmiast.

Dokumentacja API#

ScrollArea#

Kontener przewijania: element główny, viewport, pionowy ScrollBar i narożnik. className trafia do elementu głównego, a elementy potomne renderują się w viewporcie. Przyjmuje wszystkie propsy ScrollArea.Root z Base UI.

ScrollBar#

Pasek przewijania z suwakiem. Do przewijania w bok dodaj pasek z orientation="horizontal". Przyjmuje wszystkie propsy ScrollArea.Scrollbar z Base UI.

Atrybuty danych#

Ustawiane na elemencie głównym; używaj ich do stylizowania krawędzi i stanów.