Slider
StabilnyWybiera wartość lub zakres wartości przez przeciąganie wzdłuż toru — sprawdza się najlepiej, gdy przybliżone położenie liczy się bardziej niż dokładna liczba.
Anatomia
- 1TorPełny zakres wartości w neutralnym odcieniu.
- 2ZakresWybrana część zakresu, wypełniona kolorem marki — od początku toru albo między dwoma uchwytami.
- 3UchwytElement, który się przeciąga. To on przyjmuje fokus i ma obszar klikalny 32 px; dodaj drugi uchwyt, aby wybierać zakres.
Instalacja
$ pnpm dlx shadcn@latest add https://www.prfct.dev/r/slider.jsonUżycie
import { Slider } from "@/components/ui/slider"<Slider defaultValue={50} aria-label="Volume" />Przekaż liczbę, aby uzyskać jeden uchwyt, albo tablicę, aby uzyskać zakres — po jednym uchwycie na każdą wartość. Wypełniona część toru i obramowanie uchwytu mają kolor marki.
Przykłady
Z etykietą i wartością
Pokazuj bieżącą wartość obok etykiety zawsze, gdy liczba ma znaczenie. Nazwij suwak przez aria-labelledby wskazujące widoczną etykietę; nazwa trafia do uchwytu, bo to na nim faktycznie ustawia się fokus czytnika ekranu.
Zakres
Wartość w postaci tablicy renderuje dwa uchwyty. minStepsBetweenValues nie pozwala im na siebie nachodzić, a getAriaLabel nadaje każdemu uchwytowi własną nazwę — Cena minimalna i Cena maksymalna — żeby nie były odczytywane jako dwa identyczne suwaki.
Kroki
step przyciąga wartość do wielokrotności kroku. Przy kilku dyskretnych wartościach narysuj pod torem etykiety podziałki i opisz wartość słowami przez getAriaValueText — 3 repliki mówią więcej niż samo 3.
Pionowy
orientation="vertical" pasuje do kontrolek, które kojarzą się z wysokością — poziomów, korektorów, powiększenia. Wysokość suwaka nadaj przez jego kontener.
Wyłączony
Wyłączony suwak nadal pokazuje wartość, choć jest półprzezroczysty, i nie reaguje na interakcję. Jeśli powód nie jest oczywisty, wyjaśnij go obok.
Wytyczne
Kiedy używać
- Gdy względne położenie liczy się bardziej niż precyzja: głośność, krycie, powiększenie, przedział cenowy.
- Gdy ludziom pomaga widok wartości na tle całego zakresu.
Kiedy nie używać
- Gdy liczy się dokładna liczba — użyj komponentu Input z
type="number"albo połącz z nim suwak. - Przy bardzo dużych zakresach, w których jeden piksel obejmuje wiele wartości — użyj pola liczbowego.
- Przy kilku nazwanych opcjach — użyj komponentu Radio Group lub Toggle Group.
Pokazuj wartość
Suwak bez widocznej wartości każe ludziom zgadywać. Pokaż wartość obok etykiety, sformatuj ją ($240, 80%) propem format albo własną funkcją formatującą i aktualizuj ją na żywo podczas przeciągania.
Zatwierdzaj raz, nie zasypuj żądaniami
onValueChange wywołuje się bez przerwy podczas przeciągania — używaj go do aktualizowania widoku. Do zapisu lub pobierania danych po zakończeniu przeciągania użyj onValueCommitted, żeby jedna zmiana nie wysłała pięćdziesięciu żądań.
Dostępność
Każdy uchwyt zawiera natywny <input type="range">, więc suwak od razu działa z czytnikami ekranu, sterowaniem głosowym i funkcjami formularzy w przeglądarce.
| Klawisz | Działanie |
|---|---|
Tab | Przenosi fokus na następny uchwyt. Każdy uchwyt zakresu ma własne miejsce w kolejności tabulacji. |
→↑ | Zwiększa wartość o jeden krok. |
←↓ | Zmniejsza wartość o jeden krok. |
PageUpShift↑ | Zwiększa wartość o duży krok (domyślnie 10). |
PageDownShift↓ | Zmniejsza wartość o duży krok. |
HomeEnd | Ustawia wartość minimalną lub maksymalną. |
- Nadaj nazwę. Użyj
aria-labelledbywskazującego widoczną etykietę alboaria-label. prfct przekazuje nazwę do uchwytów; w zakresie nazwij każdy uchwyt przezgetAriaLabel. - Opisz wartość.
formatkształtuje zarówno widoczną, jak i odczytywaną wartość;getAriaValueTextnadpisuje to, co jest odczytywane, gdy słowa wyrażają wartość lepiej niż liczby. - Krawędzie. Uchwyt ma obramowanie 2 px w kolorze marki, które zapewnia mu kontrast co najmniej 3:1 na każdej powierzchni (WCAG 1.4.11). Tor nie jest potrzebny do rozpoznania kontrolki, więc może pozostać stonowany.
- Rozmiar celu. Uchwyty mają 16 px, a ich przezroczysty obszar klikalny — 32 × 32 px; po najechaniu i podczas przeciągania lekko się powiększają.
Dokumentacja API
Slider
Renderuje <div role="group"> z torem i jednym uchwytem na każdą wartość. Przyjmuje wszystkie propsy Slider.Root z Base UI.