Collapsible

Instalacja#

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

Użycie#

import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@/components/ui/collapsible"

<Collapsible>
  <CollapsibleTrigger render={<Button variant="ghost" size="sm" />}>
    Show details
  </CollapsibleTrigger>
  <CollapsibleContent>Anything you want to reveal.</CollapsibleContent>
</Collapsible>

CollapsibleTrigger renderuje <button> bez stylów. Żeby nadać mu wygląd, przekaż przez render Button z prfct — zachowa on własne style i zyska działanie oraz atrybuty ARIA wyzwalacza.

Przykłady#

Pokaż więcej#

Odsłoń resztę długiego podsumowania. Kontroluj open, gdy etykieta wyzwalacza ma się zmieniać razem ze stanem — Pokaż wszystkie zmiany zmienia się w Pokaż mniej.

Drzewo plików#

Komponenty Collapsible bez problemu się zagnieżdżają, dlatego są podstawą drzew. Każdy folder to osobny Collapsible; strzałka odczytuje atrybut data-panel-open swojego wyzwalacza, więc każdy poziom obraca się niezależnie.

Ustawienia zaawansowane#

Schowaj rzadko zmieniane opcje pod najważniejszymi polami formularza. Pola pozostają w kolejności DOM dokładnie tam, gdzie mają zastosowanie, więc formularz nadal czyta się od góry do dołu.

Ruch#

CollapsibleContent animuje zmierzoną wysokość (--collapsible-panel-height) z czasem trwania base i krzywą przejścia standard, w tym samym takcie płynnie pokazując lub ukrywając treść. Animację wyłączysz, nadpisując przejście w swojej kopii komponentu, a o ograniczony ruch nie musisz się martwić: przy prefers-reduced-motion panel otwiera się natychmiast.

Wytyczne#

Kiedy używać#

• Do ukrycia jednego bloku drugorzędnej treści za czytelną etykietą: szczegółów, opcji zaawansowanych, reszty długiej listy.
• Jako podstawa własnych wzorców rozwijania treści — drzew plików, sekcji paska bocznego, podsumowań z „pokaż więcej”.

Kiedy nie używać#

• Do kilku powiązanych sekcji, które mają działać jako zestaw — użyj komponentu Accordion.
• Do treści, która ma unosić się nad stroną — użyj komponentu Popover.
• Do ukrywania treści potrzebnej do wykonania bieżącego zadania.

Nazwij efekt#

Wyzwalacz powinien mówić, co się pojawi — Ustawienia zaawansowane, Pokaż wszystkie zmiany, Jeszcze 3 pliki — a nie tylko Więcej. Połącz tekst z obracającą się strzałką; sama ikona nie mówi, co jest ukryte.

Zostaw wyzwalacz na miejscu#

Umieść wyzwalacz przed treścią, którą steruje, i nie przesuwaj go po otwarciu panelu. Użytkownik powinien móc zamknąć to, co właśnie otworzył, bez szukania kontrolki.

Dostępność#

Wyzwalacz to natywny <button> z aria-expanded, a gdy panel jest otwarty — także z aria-controls wskazującym na panel.

• Wyszukiwanie na stronie. Ustaw hiddenUntilFound na CollapsibleContent, a przeglądarka będzie mogła przeszukiwać zamknięty panel i otworzy go po znalezieniu dopasowania.
• Fokus zostaje na miejscu. Otwarcie panelu nie przenosi fokusu; następne naciśnięcie Tab przeniesie go do środka.
• Własne wyzwalacze. Gdy przez render renderujesz coś innego niż Button, upewnij się, że to nadal prawdziwy przycisk — albo przekaż nativeButton={false}, żeby Base UI dodał semantykę przycisku.

Dokumentacja API#

Collapsible#

Zarządza stanem otwarcia. Renderuje <div>. Przyjmuje wszystkie propsy Collapsible.Root z Base UI.

CollapsibleTrigger#

Przycisk, który otwiera i zamyka panel. Gdy panel jest otwarty, dostaje data-panel-open — to przydatne przy obracaniu ikon. Przyjmuje wszystkie propsy Collapsible.Trigger z Base UI, w tym render i nativeButton.

CollapsibleContent#

Panel. Domyślnie animuje swoją wysokość.

Atrybuty data#