Chuyển tới nội dung

Pro đang mở bán trước. Cài đặt mở từ tháng 1/2027. Xem Pro

werewolf-ui
Component

Pagination

Chuyển giữa các trang của một danh sách hoặc table dài: Previous, các số trang quanh trang hiện tại, Next. Các trang là link thật khi có URL (getHref), hoặc button gọi onPageChange. Chúng trông như Button nhỏ: ghost, và secondary cho trang hiện tại.

  • npm: 1 trực tiếp, 4 tổng
  • registry: 3 trực tiếp, 3 tổng

Xem trước

Props

  • page
  • pageCount
  • siblingCount
  • isActive
import { Pagination } from "@/components/ui/pagination"

<Pagination page={4} pageCount={12} onPageChange={goToPage} />

Cách dùng

Khi nào dùng

  • Chuyển giữa các trang của một danh sách hoặc table dài, khi đã biết tổng số trang.
  • Các danh sách mà trang có URL, để một trang chia sẻ và tải lại được.

Khi nào không dùng

  • Một danh sách ngắn. Hiện cả danh sách.
  • Các bước của một flow.
  • Các mục của cùng một trang. Dùng Tabs.

Ví dụ

Link

Mỗi trang có một URL, nên các trang là link thật.

import { Pagination } from "@/components/ui/pagination"

<Pagination page={4} pageCount={12} getHref={pageHref} />

Button

Không có URL: các trang gọi onPageChange.

import { Pagination } from "@/components/ui/pagination"

<Pagination page={1} pageCount={5} onPageChange={goToPage} />

Nên và không nên

Nên

  • Cho các trang một URL bằng getHref khi danh sách có URL, để một trang chia sẻ và tải lại được.
  • Đặt nó dưới danh sách mà nó phân trang, và chuyển focus lên đầu danh sách sau khi đổi trang.
  • Nêu có bao nhiêu kết quả ở gần danh sách, không chỉ số lượng trang.
  • Khi trang kế tải từ server, đổi trang trong một transition (useTransition) và giữ các hàng hiện tại trên màn hình bằng Table pending, thay vì làm trống danh sách.

Không nên

  • Đừng dùng cho các bước của một flow.
  • Đừng phân trang một danh sách ngắn; hiện cả danh sách.
  • Đừng đổi siblingCount giữa các trang của cùng một danh sách; các link sẽ nhảy.

Props

TênKiểuGiá trịMặc địnhMô tả
pagenumber--Đặt trên Pagination. Trang hiện tại, bắt đầu từ 1.
pageCountnumber--Đặt trên Pagination. Có bao nhiêu trang.
onPageChangefunction--Đặt trên Pagination. Được gọi với trang cần tới, khi các trang là button.
siblingCountnumber-1Đặt trên Pagination. Số trang hiện ở mỗi bên của trang hiện tại. Trang đầu và trang cuối luôn hiện.
getHreffunction--Đặt trên Pagination. Trả về URL của một trang: (page) => `?page=${page}`. Với prop này, các trang là link thật, nên mở được trong tab mới và hoạt động không cần JavaScript.
isActiveboolean-falseĐặt trên PaginationLink trong bố cục riêng của bạn. Đánh dấu trang hiện tại.

Cấu tạo

PhầnMô tả
rootPagination: một nav tên Pagination. Khi có page và pageCount thì vẽ mọi phần bên dưới; khi có children thì chứa PaginationContent riêng của bạn.
contentPaginationContent: hàng các item, gap-xs, có xuống dòng.
itemPaginationItem: một slot trong hàng.
linkPaginationLink: một trang, một Button ghost sm rộng ít nhất bằng chiều cao, với chữ số tabular. Trang hiện tại là secondary.
stepPaginationPrevious và PaginationNext: các Button ghost sm với caret 16px và chữ Previous và Next.
ellipsisPaginationEllipsis: Tabler DotsThree, 16px, thay cho các trang bị bỏ.
hitArea::before trong suốt trên mọi link, không bao giờ nhỏ hơn size-target-min.

Khả năng truy cập

Role: navigation

PhímHành động
TabĐi qua Previous, các trang và Next.
Enter, SpaceTới trang đó (Space chỉ trên button).
  • nav được đặt tên Pagination. Mỗi trang được đặt tên Page 3, và trang hiện tại mang aria-current="page".
  • Trang hiện tại nổi bật nhờ viền và nền, không chỉ nhờ màu.
  • Previous ở trang đầu và Next ở trang cuối thì disabled: button nhận disabled, link mất href và nhận aria-disabled.
  • Ellipsis mang tính trang trí; các số trang quanh nó cho biết khoảng trống ở đâu.
  • Mỗi link trang giữ một vùng chạm size-target-min.

Cài đặt

npx werewolf-ui add pagination

Chạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.