Pagination
primitives de pagination composables pour naviguer dans le contenu paginé sans routage ni logique de données.
Navigation contrôlée pour le contenu paginéLien vers la section
Les Pagination component fournit des primitives d'interface utilisateur composables pour la navigation dans le contenu paginé.
Utilisez-le pour:
- tableaux de données
- Listes d'administration
- rapports
- factures
- utilisateurs
- projets
- résultats de recherche
- Vues du tableau de bord
La pagination est intentionnelle idiot. Il ne possède pas de routage, de récupération, de synchronisation d'URL, de logique de curseur, de logique de taille de page ou d'état de serveur.
La page ou la couche de données possède la logique. L'interface utilisateur rend la navigation.
Idée de base
La pagination devrait rendre la navigation de page, pas posséder le modèle de données.
ImportationLien vers la section
import { Pagination } from "@pycolors/ui";Utilisation de baseLien vers la section
La pagination est composée de petites primitives :
Paginationà l'élément de navigation wrapperPaginationContentListe des conteneursPaginationItemà l'emballage d'articlePaginationLinkpour le contrôle de pagePaginationPrevious/PaginationNextContrôles directionnelsPaginationEllipsisà l'indicateur de débordement compact
Page 1 / 12
Composition du lienLien vers la section
PaginationLink, PaginationPreviouset PaginationNext Soutenez le asChild modèle de composition. Passer une ancre réelle (ou un cadre) Link) comme l'enfant et le contrôle le rend comme élément racine tout en préservant tous les styles, data-slot, étiquettes accessibles, et - pour PaginationPrevious et PaginationNext - l'icône intégrée et le texte visible.
Liens du cadre
Remplacer <a href="..."> avec votre routeur Link composant (Next.js, React Router, TanStack Router, etc.) - le modèle de composition est routeur-neutre.
PaginationPrécédent et PaginationSuivant avec asChild
Vous n'avez qu'à fournir l'élément d'ancrage en tant qu'enfant. L'icône intégrée ChevronLeft / ChevronRight et le texte visible Précédent / Suivant sont automatiquement affichés à côté de votre élément enfant.
Utilisez Pagination lorsque les utilisateurs ont besoin d'un accès contrôlé à un ensemble fini de pages.
Tableaux
Données mises en page
Résultats de la recherche
Tableau + PaginationLien vers la section
Cet exemple illustre un modèle SaaS commun : une table avec contrôle de pagination local.
Aucune logique backend n'est incluse. Remplacez la tranche simulée par votre couche de données réelle plus tard.
| Nom | Statut | Mise à jour | Actions |
|---|---|---|---|
| Project 1 | Actif | 2026-01-21 | |
| Project 2 | Actif | 2026-01-21 | |
| Project 3 | En pause | 2026-01-21 | |
| Project 4 | Actif | 2026-01-21 | |
| Project 5 | Archivé | 2026-01-21 |
Affichage de 1–5 sur 23
Règle d'architecture
Pagination devrait recevoir des rappels d'état et de rappel. La couche de fonctionnalités doit posséder la source de données, les filtres, le tri et la synchronisation d'URL.
buildPaginationRangeLien vers la section
Utilisation buildPaginationRange pour générer des tokens de page compacts avec ellipse.
const tokens = buildPaginationRange({
page,
totalPages,
});Les tokens retournés peuvent représenter :
- Numéros de page
- Page active
- marqueurs d'ellipse
Cela maintient la logique de rendu propre tout en gardant Pagination contrôlée.
UtilisationsLien vers la section
Conserver l'état de la page en dehors du composant
Stocker page, pageSizeet totalPages dans la page, le crochet de fonctionnalité ou la couche de données.
Désactiver la navigation impossible
Désactiver Précédent sur la première page et Suivant sur la dernière page.
Utiliser l'ellipse pour les grands nombres de pages
Évitez de rendre des dizaines de liens de page. Larges gammes compactes avec ellipses.
Synchronisation de l'URL uniquement au niveau de la couche produit
La synchronisation d'URL appartient à votre page ou couche de routage, pas à la primitive d'interface utilisateur.
Paire avec états de chargement et de vide
La pagination doit fonctionner avec la table, les états de chargement, les états vides et les filtres comme un modèle de produit.
Pagination vs défilement infiniLien vers la section
| Situation | Utilisation |
|---|---|
| Tableau d'administration | Pagination |
| Résultats de recherche avec nombre de pages connu | Pagination |
| Factures, utilisateurs, abonnements | Pagination |
| Navigation sous forme de flux | Défilement infini |
| API Cursor uniquement sans concept de page | Contrôles du curseur au niveau du produit |
| Petit ensemble de données | Pas de pagination |
Règle de décision
Utilisez Pagination lorsque l'utilisateur bénéficie d'une position stable dans un ensemble de résultats finis.
APILien vers la section
Composante
| Composante | Désignation |
|---|---|
Pagination | Wrapper nav élément avec la sémantique de pagination |
PaginationContent | Liste des conteneurs |
PaginationItem | Emballage d'article |
PaginationLink | Contrôle de page avec état actif |
PaginationPrevious | Bouton précédent |
PaginationNext | Bouton suivant |
PaginationEllipsis | Indicateur de débordement visuel |
PaginationLink accessoires
| Prop | Type | Par défaut | Désignation |
|---|---|---|---|
asChild | boolean | false | Rendu comme une enveloppe de fente; fournir une ancre réelle ou un lien de cadre comme l'enfant |
isActive | boolean | false | Marque la page actuelle |
size | string | "icon-sm" | Cartes à tailles de boutons |
className | string | — | Autres classes Tailwind |
PaginationPrécédent
| Prop | Type | Par défaut | Désignation |
|---|---|---|---|
asChild | boolean | false | Rendu en tant que wrapper Slot; icône et texte intégrés sont préservés |
label | string | "Previous page" | Étiquette accessible pour les lecteurs d'écran |
className | string | — | Autres classes Tailwind |
PaginationProchains accessoires
| Prop | Type | Par défaut | Désignation |
|---|---|---|---|
asChild | boolean | false | Rendu en tant que wrapper Slot; icône et texte intégrés sont préservés |
label | string | "Next page" | Étiquette accessible pour les lecteurs d'écran |
className | string | — | Autres classes Tailwind |
Options de buildPaginationRange
| Variante | Type | Désignation |
|---|---|---|
page | number | Page actuelle |
totalPages | number | Nombre total de pages |
AccessibilitéLien vers la section
La pagination doit être compréhensible et accessible au clavier.
Directives :
- Utiliser la sémantique
navavec étiquetage de pagination - marquer la page active avec
aria-current="page" - garder les boutons clavier accessible
- Désactiver les options Précédent et Suivant en cas d'indisponibilité
- rendre l'ellipse non interactive
- éviter les clics minuscules dans les mises en page denses
- fournir une synchronisation d'URL au niveau du calque de page lorsque la liaison profonde est importante
Règle d'accessibilité
Les contrôles de pagination doivent être navigables, compréhensibles et prévisibles sans dépendre uniquement de la position visuelle.
Préférez/évitezLien vers la section
Préférez
- État de page contrôlé
- Contrôles désactivés non disponibles
- ellipses pour les grands nombres de pages
- Synchronisation d'URL dans le calque de route si nécessaire
- Effacer les états de chargement et de vide autour des données paginées
Éviter
- récupérer des données dans Pagination
- rendu de chaque page pour de grandes gammes
- ellipse cliquable
- pagination pour les ensembles de données minuscules
- Utilisation de la pagination pour la découverte de style feed
Directives de copie du produitLien vers la section
Les étiquettes de pagination doivent être courtes et prévisibles.
Précédent / Suivant
Use familiar labels for core navigation. Avoid clever wording or ambiguous actions.