Breadcrumb

Anatomia#

Instalacja#

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

Użycie#

import Link from "next/link"

import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@/components/ui/breadcrumb"

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink render={<Link href="/docs" />}>Docs</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

BreadcrumbLink domyślnie renderuje <a>; przekaż link swojego routera przez render, aby zachować nawigację po stronie klienta. Ostatni element to BreadcrumbPage — bieżąca lokalizacja, która nie jest linkiem.

Przykłady#

Domyślny#

prfct oddziela poziomy subtelnym ukośnikiem. Czyta się go jak ścieżkę, zajmuje mniej miejsca niż strzałka i nie konkuruje z linkami.

Własny separator#

Przekaż dowolną ikonę jako dziecko BreadcrumbSeparator. Strzałki pasują do ustawień i hierarchii plików, w których ścieżka oznacza schodzenie w głąb.

Zwinięta ścieżka#

Gdy ścieżka ma więcej niż cztery poziomy, zostaw poziom główny i dwa ostatnie, a środek zwiń do menu rozwijanego Dropdown Menu ukrytego za wielokropkiem. Nic nie staje się nieosiągalne.

Z ikonami#

Ikona domu może zastąpić poziom główny, gdy nazwa produktu jest już widoczna w nagłówku — nadaj jej wtedy aria-label. Ikony w środku ścieżki powinny oznaczać rodzaj poziomu, a nie go ozdabiać.

Przełącznik#

W aplikacjach ostatni segment może jednocześnie przełączać między elementami tego samego poziomu — projektami w zespole, gałęziami w repozytorium. Wyzwalacz wygląda jak bieżąca strona, a menu oznacza aktywny element.

Wytyczne#

Kiedy używać#

• W hierarchiach o głębokości co najmniej trzech poziomów — w dokumentacji, systemach plików, ustawieniach, kategoriach sklepów internetowych.
• Gdy ktoś trafia głęboko w strukturę z wyszukiwarki lub udostępnionego linku i musi się zorientować, gdzie jest.

Kiedy nie używać#

• W płaskich serwisach z jednym lub dwoma poziomami — wystarczy tytuł strony.
• Do pokazywania kolejnych kroków lub historii — ścieżka nawigacji opisuje położenie, a nie drogę, którą ktoś przeszedł. W procesach wieloetapowych użyj wskaźnika kroków.
• Jako nawigacji głównej. Ścieżka nawigacji uzupełnia Sidebar lub Navigation Menu, ale ich nie zastępuje.

Treść#

Każdy element używa tytułu strony docelowej, skróconego tylko w razie potrzeby. Nie linkuj bieżącej strony, nie powtarzaj jej tuż poniżej jako tytułu strony w innym brzmieniu i nie dodawaj separatora na końcu.

Umiejscowienie#

Umieść ścieżkę nawigacji nad tytułem strony, wyrównaną z nim do lewej, w kolumnie treści. Na wąskich ekranach zwiń ją do poziomu głównego i nadrzędnego albo pokaż tylko link Wróć do poziomu wyżej.

Dostępność#

• Punkt orientacyjny. Breadcrumb renderuje <nav> z etykietą Ścieżka nawigacji (tłumaczoną przez LocaleProvider), więc użytkownicy czytników ekranu mogą przejść do niego z listy punktów orientacyjnych.
• Kolejność. Elementy tworzą listę uporządkowaną (<ol>), która przekazuje hierarchię i liczbę poziomów.
• Bieżąca strona. BreadcrumbPage jest prezentowany technologiom wspomagającym jako wyłączony link z aria-current="page", więc czytnik ekranu ogłasza go jako bieżącą lokalizację. Nie przyjmuje fokusu.
• Separatory mają aria-hidden, więc nie są odczytywane między poziomami.
• Zwinięte poziomy wymagają wyzwalacza z dostępną nazwą, np. Pokaż ukrytą ścieżkę.

Dokumentacja API#

Breadcrumb#

Punkt orientacyjny <nav>. Przyjmuje wszystkie propsy elementu <nav>; nadpisz aria-label, gdy strona ma więcej niż jedną ścieżkę nawigacji.

BreadcrumbList i BreadcrumbItem#

BreadcrumbList to <ol>, który układa ścieżkę i zawija ją na wąskich ekranach. BreadcrumbItem to <li>, który wyrównuje swoją zawartość — link, bieżącą stronę lub wyzwalacz menu.

BreadcrumbLink#

BreadcrumbPage#

Bieżąca lokalizacja. Renderuje <span> z aria-current="page".

BreadcrumbSeparator#

BreadcrumbEllipsis#

Znak ⋯ dla zwiniętych poziomów, odczytywany jako Więcej w języku ustawionym przez LocaleProvider. W wyzwalaczu nadaj samemu wyzwalaczowi nazwę, która mówi, co odsłania.