Toggle Group

Anatomia#

Instalacja#

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

Użycie#

import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

<ToggleGroup defaultValue={["left"]} aria-label="Text alignment">
  <ToggleGroupItem value="left" aria-label="Align left">
    <AlignLeftIcon />
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">
    <AlignCenterIcon />
  </ToggleGroupItem>
</ToggleGroup>

Wartość jest zawsze tablicą wartości wciśniętych elementów — ["left"] przy pojedynczym wyborze, ["bold", "italic"] przy kilku.

Przykłady#

Wielokrotny wybór#

Dodaj multiple, żeby można było wcisnąć naraz dowolną liczbę elementów — jak na pasku formatowania.

Kontrolka segmentowa#

spacing={0} w połączeniu z wariantem outline scala elementy w jedną kontrolkę ze wspólnymi obramowaniami — kontrolkę segmentową do przełączania między kilkoma widokami tej samej treści.

Przełącznik widoku#

W grupie jednokrotnego wyboru ponowne naciśnięcie aktywnego elementu zwalnia go i nic nie zostaje wybrane. Gdy jedna opcja musi być zawsze aktywna, kontroluj wartość i ignoruj puste aktualizacje.

const [view, setView] = React.useState("grid")

<ToggleGroup
  value={[view]}
  onValueChange={(value) => value.length > 0 && setView(value[0])}
  aria-label="View"
>
  …
</ToggleGroup>

Układ pionowy#

orientation="vertical" układa elementy jeden pod drugim i przełącza nawigację klawiaturą na strzałki w górę i w dół — to układ palety narzędzi.

Rozmiary#

size dotyczy wszystkich elementów: sm 32, default 36, lg 40.

Wytyczne#

Kiedy używać#

• Do przełączania między dwoma–pięcioma widokami lub trybami tej samej treści: Dzień · Tydzień · Miesiąc, siatka albo lista.
• Na paskach narzędzi z powiązanymi opcjami — jednokrotnego wyboru (wyrównanie) lub wielokrotnego (styl tekstu).

Kiedy nie używać#

• Do wyborów w formularzu, który zostanie wysłany później — użyj Radio Group: jest odbierany jako pole formularza i obsługuje opisy.
• Przy więcej niż pięciu–sześciu opcjach albo długich etykietach — użyj Select.
• Do niepowiązanych akcji — użyj Button Group. Grupa przycisków przełączających sugeruje wspólny stan.
• Do przełączania widoków, z których każdy ma własny panel — użyj Tabs. Do nawigacji między stronami służą linki.

Krótkie i jednorodne etykiety#

Segmenty powinny być tego samego rodzaju i mieć zbliżoną długość — wtedy kontrolka jest odbierana jako jeden zestaw. Ikony sprawdzają się na paskach narzędzi; przy trybach lepiej działają słowa.

Dostępność#

• Grupa renderuje role="group"; nazwij ją przez aria-label albo aria-labelledby wskazujące widoczną etykietę.
• Każdy element to przycisk przełączający z aria-pressed. Elementy z samą ikoną potrzebują aria-label.
• Grupa zajmuje jedno miejsce w kolejności tabulacji, a fokus wędruje w jej obrębie (roving focus): Tab przenosi fokus do grupy, strzałki przesuwają go między elementami, a na końcach fokus przeskakuje na przeciwny koniec grupy (loopFocus).

Dokumentacja API#

ToggleGroup#

Renderuje <div> z role="group". Przyjmuje wszystkie propsy komponentu Toggle Group z Base UI.

ToggleGroupItem#

Toggle, który zgłasza grupie swoje value. Renderuje <button>.