Checkbox

Anatomia#

Instalacja#

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

Użycie#

import { Checkbox } from "@/components/ui/checkbox"
import { Field, FieldLabel } from "@/components/ui/field"

<Field orientation="horizontal">
  <Checkbox id="terms" />
  <FieldLabel htmlFor="terms">Accept terms and conditions</FieldLabel>
</Field>

Po zaznaczeniu pola znacznik rysuje się sam, jak pociągnięcie pióra. Pola zaznaczone i w stanie pośrednim wypełniają się kolorem marki — w prfct kolor oznacza stan i zaznaczenie, a czerń jest zarezerwowana dla akcji.

Przykłady#

Z opisem#

Umieść etykietę i opis w FieldContent obok pola wyboru. Opis wyjaśnia konsekwencje, a etykieta pozostaje na tyle krótka, żeby dało się ją szybko przejrzeć wzrokiem.

Stan pośredni#

Nadrzędne pole wyboru, które steruje grupą, jest w stanie pośrednim, gdy zaznaczona jest tylko część pól podrzędnych. Ustaw indeterminate razem z checked; kliknięcie pola nadrzędnego zaznacza wtedy albo czyści wszystkie pola podrzędne. Dodaj polom podrzędnym wcięcie, żeby hierarchia była widoczna, a nie tylko sugerowana.

Stany#

Wyłączone pola wyboru blakną do połowy krycia i ignorują interakcję. Przy błędzie oznacz pole wyboru atrybutem aria-invalid, a otaczający je Field — atrybutem data-invalid; w FieldError wyjaśnij, co zrobić — sama czerwona ramka nie wystarczy.

Karty wyboru#

Owiń cały Field w FieldLabel, żeby zamienić go w kartę do zaznaczenia: cała karta przełącza pole wyboru, a zaznaczona karta nabiera odcienia marki. Karty stosuj dla opcji, które potrzebują ceny, obrazu lub dłuższego opisu.

Grupa#

Powiązane pola wyboru umieść w FieldSet z FieldLegend, żeby technologie wspomagające odczytały pytanie — Powiadom mnie e-mailem, gdy… — raz, przy wejściu do grupy, zamiast zostawiać każdą opcję bez kontekstu. Nadaj im ten sam name i różne wartości value, żeby wysłać je jako listę.

Wytyczne#

Kiedy używać#

• Do pojedynczej, niezależnej zgody: Zapamiętaj mnie, Akceptuję regulamin.
• Do wyboru dowolnej liczby opcji z listy, także żadnej.
• Gdy zmiana zaczyna obowiązywać dopiero po wysłaniu formularza.

Kiedy nie używać#

• Do ustawień, które działają od razu — użyj komponentu Switch.
• Do wyboru dokładnie jednej opcji z zestawu — użyj komponentu Radio Group.
• Gdy opcji jest więcej niż około dziesięciu — użyj komponentu Combobox lub Select z wyborem wielokrotnym.

Etykiety#

Formułuj etykiety twierdząco, tak by opisywały stan zaznaczony. Nikt nie powinien rozszyfrowywać podwójnego przeczenia, żeby wiedzieć, co zrobi zaznaczenie pola.

Układ#

Układaj pola wyboru pionowo, po jednym w wierszu, z polem po lewej stronie etykiety. Pionowe listy szybciej się przegląda, a wszystkie etykiety są w nich wyrównane; poziome rzędy sprawdzają się tylko przy dwóch, trzech bardzo krótkich opcjach.

Dostępność#

Widoczna kontrolka ma role="checkbox" i aria-checked ("mixed" w stanie pośrednim). Base UI renderuje ukryte natywne pole input na potrzeby wysyłania i walidacji formularza, przypisuje mu id pola wyboru i łączy sąsiedni <label htmlFor> z widoczną kontrolką przez aria-labelledby — dzięki temu etykiety są zarówno klikalne, jak i odczytywane.

• Zawsze dodawaj etykietę. Użyj FieldLabel z htmlFor, owiń pole wyboru etykietą albo użyj aria-label — ale tylko wtedy, gdy widoczna etykieta byłaby naprawdę zbędna (np. pole zaznaczania wiersza w tabeli z czytelnym nagłówkiem kolumny).
• Krawędzie. Obramowanie niezaznaczonego pola używa tokenu input — 3:1 względem strony, zgodnie z WCAG 1.4.11. Stan zaznaczenia przekazuje też znacznik, a nie sam kolor.
• Rozmiar celu. Pole ma 16 px, ale niewidoczny obszar kliknięcia powiększa je do 24 × 24 px (WCAG 2.2, 2.5.8), nie wpływając na układ. Pole przełącza też kliknięcie etykiety.
• Grupy. Użyj FieldSet i FieldLegend, żeby pytanie grupy zostało odczytane. W hierarchii rodzic–dzieci aria-checked="mixed" na polu nadrzędnym informuje użytkowników czytników ekranu, że zaznaczono tylko część pól podrzędnych.

Dokumentacja API#

Checkbox#

Renderuje <span role="checkbox"> i ukryty <input>. Przyjmuje wszystkie propsy Checkbox.Root z Base UI.