Pagination

Anatomia#

Instalacja#

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

Użycie#

import {
  Pagination,
  PaginationContent,
  PaginationEllipsis,
  PaginationItem,
  PaginationLink,
  PaginationNext,
  PaginationPrevious,
} from "@/components/ui/pagination"

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="?page=1" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2" isActive>
        2
      </PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="?page=3" />
    </PaginationItem>
  </PaginationContent>
</Pagination>

Strony to prawdziwe linki. Umieść numer strony w adresie URL (?page=3), aby wyniki dało się udostępnić, dodać do zakładek, przywrócić przyciskiem Wstecz i zaindeksować w wyszukiwarkach.

Przykłady#

Domyślna#

Bieżąca strona dostaje isActive, który przełącza ją na styl z obrysem i ustawia aria-current="page". Poniżej breakpointu sm linki Poprzednia i Następna zwijają się do samych strzałek.

Kontrolowana z zakresem stron#

Gdy stron jest dużo, pokaż pierwszą, ostatnią i bieżącą wraz z sąsiednimi; luki zastąp komponentem PaginationEllipsis. Liczba elementów nie zmienia się podczas przechodzenia między stronami, więc kontrolki nie przesuwają się pod kursorem.

Kompaktowa#

Gdy brakuje miejsca albo konkretna strona jest mniej ważna niż kierunek, pokaż pozycję jako tekst między dwoma linkami z ikonami. Każdemu z tych linków nadaj aria-label.

Stopka tabeli#

W tabelach danych paginacji towarzyszy wybór liczby wierszy na stronie i podsumowanie zakresu (26–50 z 237). Po zmianie tej liczby wróć do pierwszej strony.

Wytyczne#

Kiedy używać#

• Dla zbiorów wyników, które się przeszukuje i filtruje, i do których się wraca: tabel, list w panelach administracyjnych, wyników wyszukiwania, archiwów.
• Gdy liczy się pozycja w zbiorze albo trzeba dotrzeć do końca bez wczytywania wszystkiego, co jest przed nim.

Kiedy nie używać#

• Dla strumieni treści, które się przegląda, a nie przeszukuje — lepiej sprawdzi się nieskończone przewijanie lub przycisk Wczytaj więcej.
• Gdy elementów jest mniej niż około 25 — pokaż wszystkie na jednej stronie.
• Dla kroków procesu — użyj wskaźnika kroków; strony sugerują równorzędne, niezależne od siebie części.

Paginacja, „Wczytaj więcej” czy nieskończone przewijanie#

Zachowanie#

Trzymaj kontrolkę w tym samym miejscu na każdej stronie — pod wynikami, a przy długich listach opcjonalnie także nad nimi. Po zmianie strony przewiń do początku wyników i zachowaj filtry oraz sortowanie. Pokaż łączną liczbę wyników, jeśli ją znasz — ułatwia decyzję, czy zawęzić wyszukiwanie.

Dostępność#

• Punkt orientacyjny. Pagination renderuje <nav> z etykietą Paginacja — w języku ustawionym przez LocaleProvider. Jeśli na stronie są dwie paginacje (nad wynikami i pod nimi), nadaj im różne etykiety, np. Paginacja, góra i Paginacja, dół.
• Bieżąca strona. isActive ustawia aria-current="page", więc bieżąca strona jest odczytywana przez czytniki ekranu, a nie tylko wyróżniona wizualnie.
• Linki kierunkowe mają etykiety Przejdź do poprzedniej strony i Przejdź do następnej strony — także wtedy, gdy widać tylko strzałki.
• Wielokropki są ukryte przed technologiami wspomagającymi; znaczenie niosą otaczające je numery stron.
• Wyłączone skrajne linki. Na pierwszej i ostatniej stronie ustaw aria-disabled na linku Poprzednia lub Następna i zostaw go na miejscu, aby układ nie przeskakiwał.

Dokumentacja API#

Pagination#

Punkt orientacyjny <nav>. Przyjmuje wszystkie propsy elementu <nav>.

PaginationContent i PaginationItem#

PaginationContent to element <ul>, który rozmieszcza pozycje; PaginationItem to każdy pojedynczy <li>.

PaginationLink#

Renderuje element <a> ostylowany jak Button z prfct.

PaginationPrevious i PaginationNext#

PaginationEllipsis#

Czysto prezentacyjny znak ⋯, który zastępuje pominięte strony.