Button Group

Anatomia#

Instalacja#

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

Użycie#

import { Button } from "@/components/ui/button"
import { ButtonGroup } from "@/components/ui/button-group"

<ButtonGroup aria-label="Message actions">
  <Button variant="outline">Archive</Button>
  <Button variant="outline">Snooze</Button>
  <Button variant="outline">Flag</Button>
</ButtonGroup>

Grupa usuwa zaokrąglenie wewnętrznych narożników swoich elementów i scala ich wspólne obramowania. Działa ze wszystkim, co ma atrybut data-slot — z przyciskami, polami tekstowymi, wyzwalaczami list wyboru i menu rozwijanych oraz z ButtonGroupText.

Przykłady#

Orientacja#

orientation="vertical" układa elementy jeden pod drugim i łączy je w pionie — to klasyczna kontrolka powiększenia.

Z separatorami#

Warianty wypełnione nie mają obramowań, które mogłyby się połączyć, więc dodaj między elementami ButtonGroupSeparator, żeby dało się je od siebie odróżnić.

Z polami#

Dołącz przycisk do pola wyszukiwania albo pola z wartością do skopiowania, a dla stałych prefiksów i sufiksów, takich jak protokoły i domeny, użyj ButtonGroupText.

Przycisk dzielony#

Połącz akcję główną z menu alternatyw. Główny przycisk uruchamia najczęściej wybieraną opcję, a strzałka otwiera pozostałe.

<ButtonGroup>
  <Button>Merge pull request</Button>
  <ButtonGroupSeparator className="bg-primary-foreground/30" />
  <DropdownMenu>
    <DropdownMenuTrigger render={<Button size="icon" aria-label="More merge options" />}>
      <ChevronDownIcon />
    </DropdownMenuTrigger>
    <DropdownMenuContent align="end">…</DropdownMenuContent>
  </DropdownMenu>
</ButtonGroup>

Zagnieżdżone grupy#

Grupy zagnieżdżone w grupie zachowują własne połączone krawędzie i są od siebie odsunięte — tak paski narzędzi zbierają powiązane narzędzia w zestawy.

Wytyczne#

Kiedy używać#

• Do niewielkiego zestawu powiązanych, równorzędnych akcji na tym samym obiekcie: Archiwizuj, Odłóż, Oznacz flagą.
• Aby dołączyć akcję do pola, np. wyszukiwanie lub kopiowanie.
• Do przycisków dzielonych, w których jedna akcja jest domyślna, a pozostałe są jej odmianami.

Kiedy nie używać#

• Do wyboru spośród opcji — użyj komponentu Toggle Group, który śledzi, co jest zaznaczone.
• Do akcji o różnej wadze. Grupa sugeruje równorzędność; akcja główna i przycisk anulowania powinny być osobnymi przyciskami z odstępem między nimi.
• Do długich list akcji. Powyżej czterech–pięciu elementów przenieś resztę do menu Dropdown Menu.

Zachowaj spójne warianty#

Wszystkie elementy grupy powinny mieć ten sam wariant i ten sam rozmiar. Różne warianty rozbijają wspólną sylwetkę, dzięki której grupę odbiera się jako jedną kontrolkę.

Dostępność#

• Grupa renderuje role="group". Nadaj jej aria-label (lub aria-labelledby), który nazywa zestaw — Akcje wiadomości, Powiększenie mapy — żeby czytnik ekranu ogłosił kontekst, gdy fokus wejdzie do grupy.
• Każdy element zachowuje własną semantykę i własne miejsce w kolejności tabulacji. W odróżnieniu od Toggle Group nie ma tu wędrującego fokusu (roving focus): przyciski w grupie to niezależne akcje.
• Przyciski z samą ikoną wewnątrz grupy nadal potrzebują aria-label.
• Element z fokusem trafia na wierzch, więc sąsiednie obramowanie nigdy nie przycina pierścienia fokusu.

Dokumentacja API#

ButtonGroup#

Renderuje <div> z role="group" i data-slot="button-group".

ButtonGroupText#

Nieinteraktywny segment na prefiksy, sufiksy i etykiety. Renderuje <div>; użyj render, aby podmienić element.

ButtonGroupSeparator#

Cienka linia między elementami dla wariantów bez obramowań. Zbudowany na komponencie Separator.

buttonGroupVariants#

Generator klas, eksportowany dla własnych elementów, które mają łączyć się tak jak grupa.