Table

Anatomia#

Instalacja#

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

Użycie#

import {
  Table,
  TableBody,
  TableCaption,
  TableCell,
  TableFooter,
  TableHead,
  TableHeader,
  TableRow,
} from "@/components/ui/table"

<Table>
  <TableCaption>Usage for September 2026.</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead scope="col">Resource</TableHead>
      <TableHead scope="col" className="text-right">Cost</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Compute</TableCell>
      <TableCell className="text-right">$186.20</TableCell>
    </TableRow>
  </TableBody>
</Table>

Table otacza element <table> kontenerem przewijanym w poziomie, dzięki czemu szeroka tabela nigdy nie rozbija układu strony na małych ekranach. Liczby domyślnie korzystają z cyfr tabelarycznych, więc cyfry układają się w równe kolumny.

Przykłady#

Podpis i stopka#

Podpis nazywa tabelę dla wszystkich — to pierwsza rzecz, którą odczytuje czytnik ekranu. TableFooter mieści sumy w zabarwionym wierszu.

Tabela danych#

Zaznaczanie, sortowanie i akcje wierszy to kwestia kompozycji, a nie konfiguracji: kolumna pól wyboru, przyciski w nagłówkach, które przełączają kolejne kierunki sortowania, i menu w każdym wierszu. Pole wyboru w nagłówku przechodzi w stan pośredni, gdy zaznaczono część wierszy — ale nie wszystkie — a zaznaczone wiersze przyjmują odcień marki.

<TableHead aria-sort={sort?.key === "amount" ? sort.direction : "none"}>
  <Button variant="ghost" size="xs" onClick={() => toggleSort("amount")}>
    Amount
    <ArrowUpDownIcon data-icon="inline-end" />
  </Button>
</TableHead>

Stan pusty#

Gdy zapytanie nic nie zwraca, zostaw nagłówek — dzięki niemu wiadomo, co mogłoby się tu znaleźć — a w jednej komórce na całą szerokość tabeli umieść stan Empty, który wskazuje wyjście z sytuacji.

Ładowanie#

Podczas ładowania danych pokaż wiersze szkieletowe w kształcie prawdziwej treści i oznacz tabelę atrybutem aria-busy, żeby technologie wspomagające na nią zaczekały.

Wytyczne#

Kiedy używać#

• Do porównywania wielu obiektów według tego samego zestawu atrybutów.
• Gdy trzeba przeglądać, sortować lub filtrować wiersze albo wykonywać na nich akcje.

Kiedy nie używać#

• Do budowania układu. Tabele służą do danych; do rozmieszczania elementów na stronie używaj grid lub flex.
• Do kilku obiektów z rozbudowaną treścią — sięgnij po Card albo listę elementów Item.
• Do pól pojedynczego rekordu — użyj listy opisów.

Wyrównanie#

• Tekst do lewej, liczby do prawej. Liczby wyrównane do prawej ustawiają jedności, dziesiątki i setki w tych samych kolumnach — w połączeniu z cyframi tabelarycznymi rzędy wielkości da się porównać jednym spojrzeniem.
• Wyrównuj nagłówek tak samo jak zawartość jego kolumny — łącznie z przyciskiem sortowania.
• Jednostki podawaj w nagłówku (Koszt (USD), Czas (s)), zamiast powtarzać je w każdej komórce.

Gęstość#

Wiersze mają 48 px wysokości — to wygodna wartość dla mieszanej treści z odznakami i akcjami. W tabelach tylko do odczytu, zawierających same liczby, zmniejsz wysokość komórek przez className="h-10"; nie schodź poniżej 32 px — to najmniejszy cel, w który wygodnie trafić wskaźnikiem.

Akcje wierszy#

Akcje dotyczące jednego wiersza umieść w menu z dodatkowymi opcjami na końcu wiersza, a akcje dla wielu wierszy — na pasku narzędzi, który pojawia się po zaznaczeniu wierszy. Wiersz może być klikalny w całości albo zawierać przyciski — nigdy jedno i drugie naraz.

Dostępność#

Tabele prfct to prawdziwe elementy <table>, więc wiersze, kolumny i nagłówki są odczytywane bez dodatkowych atrybutów ARIA.

• Nazwij tabelę. Użyj TableCaption albo aria-label, jeśli tabelę nazywa już widoczny nagłówek nad nią.
• Określ zakres nagłówków. Dodaj scope="col" do nagłówków kolumn (a scope="row" do nagłówków wierszy), żeby każda komórka była odczytywana razem ze swoim nagłówkiem.
• Informuj o sortowaniu. Ustaw aria-sort na posortowanym TableHead (ascending, descending lub none). Sama ikona nie zostanie odczytana.
• Nadaj etykietę każdej kontrolce. Pola wyboru i menu w wierszach potrzebują etykiet, które nazywają wiersz — „Zaznacz płatność od Northwind Traders”, a nie „Zaznacz”.
• Zaznaczenie to nie tylko kolor. Odcień zaznaczenia zawsze idzie w parze z zaznaczonym polem wyboru — nie polegaj na samym odcieniu.

Dokumentacja API#

Każda część renderuje odpowiadający jej element HTML i przyjmuje wszystkie jego propsy.