Radio Group

Instalacja#

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

Użycie#

import { Field, FieldLabel } from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

<RadioGroup defaultValue="daily">
  <Field orientation="horizontal">
    <RadioGroupItem value="daily" id="daily" />
    <FieldLabel htmlFor="daily">Daily summary</FieldLabel>
  </Field>
  <Field orientation="horizontal">
    <RadioGroupItem value="weekly" id="weekly" />
    <FieldLabel htmlFor="weekly">Weekly summary</FieldLabel>
  </Field>
</RadioGroup>

Zaznaczony przycisk radiowy wypełnia się kolorem marki, a jego kropka sprężyście wskakuje na miejsce.

Przykłady#

Z opisami#

Gdy opcje wymagają wyjaśnienia, dodaj do każdej etykiety opis w FieldContent. Użytkownicy porównują opcje, czytając opisy jeden obok drugiego — to jeden z głównych powodów, by wybrać przyciski radiowe zamiast listy wyboru.

Karty wyboru#

Opakuj każde pole w FieldLabel, aby cała karta była klikalna. Karty sprawdzają się przy decyzjach, za którymi stoi cena, limit lub lista funkcji — wyborze planu, szybkości dostawy, środowiska wdrożenia.

Układ poziomy#

Krótkie opcje ułóż w rzędzie, gdy tworzą skalę albo zestaw równorzędnych wariantów. Nazwij grupę za pomocą FieldSet i FieldLegend — rząd przycisków radiowych bez pytania jest niejednoznaczny.

Stany#

Wyłącz grupę, gdy wybór jeszcze nie ma zastosowania, i obok wyjaśnij dlaczego. Do walidacji ustaw required, oznacz elementy przez aria-invalid i pokaż FieldError pod grupą.

Wytyczne#

Kiedy używać#

• Do wyboru dokładnie jednej opcji spośród dwóch do mniej więcej siedmiu.
• Gdy warto widzieć i porównywać wszystkie opcje jednocześnie.

Kiedy nie używać#

• Do wyboru kilku opcji — użyj Checkbox.
• Do pojedynczego ustawienia typu włącz/wyłącz — użyj Switch lub pola wyboru.
• Gdy opcji jest więcej niż około siedmiu albo brakuje miejsca — użyj Select.
• Do kompaktowych, segmentowych wyborów na paskach narzędzi (tryby widoku, wyrównanie) — użyj Toggle Group.

Domyślny wybór#

Zaznacz z góry najczęściej wybieraną lub najbezpieczniejszą opcję — gdy ktoś już dokona wyboru, grupy przycisków radiowych nie da się przywrócić do stanu „nic nie zaznaczono”, więc pusta grupa ma sens tylko wtedy, gdy wybór musi być świadomy. W takim przypadku go waliduj.

Kolejność#

Układaj opcje logicznie — według wielkości, czasu lub prawdopodobieństwa — i trzymaj listę w pionie, chyba że opcje są bardzo krótkie. Wyrównaj przyciski radiowe do lewej, aby etykiety tworzyły równą kolumnę, którą łatwo przebiec wzrokiem.

Dostępność#

RadioGroup renderuje role="radiogroup", a każdy element — role="radio" z aria-checked. Grupa zajmuje jedno miejsce w kolejności tabulacji, a fokus wędruje w jej obrębie (roving focus), zgodnie ze wzorcem ARIA dla grupy przycisków radiowych.

• Nazwij grupę. Użyj FieldSet + FieldLegend albo aria-label / aria-labelledby na RadioGroup, aby pytanie było odczytywane razem z każdą opcją.
• Nadaj etykietę każdemu przyciskowi — przez FieldLabel wskazujący jego id. Base UI łączy etykietę z widocznym przyciskiem, więc kliknięcie tekstu go zaznacza.
• Krawędzie i cele dotyku. Obramowanie przycisków radiowych korzysta z tokenu input (3:1, WCAG 1.4.11), a wokół okręgu o średnicy 16 px jest obszar kliknięcia 24 × 24 px.

Dokumentacja API#

RadioGroup#

Renderuje <div role="radiogroup">. Przyjmuje wszystkie propsy RadioGroup z Base UI.

RadioGroupItem#

Renderuje <span role="radio"> z ukrytym polem input. Przyjmuje wszystkie propsy Radio.Root z Base UI.