Pagination — Ariane

Accessibilité

Lien direct vers cette section

Pris en charge automatiquement

Lien direct vers cette section

role="navigation" et aria-labelledby posés sur le conteneur, dont le nom inclut la position courante (“Pagination, page 4 sur 12”) — repérable immédiatement en navigation par régions, sans avoir à explorer les liens pour savoir où on en est.
Les boutons “précédent” et “suivant” ont aria-disabled synchronisé avec leur état désactivé — WCAG 4.1.2 (ouvre dans un nouvel onglet)Name, Role, Value : tout composant UI doit exposer son nom, rôle et valeur (états inclus) aux technologies d'assistance.
Chaque lien de page et les boutons “précédent”/“suivant” indiquent le nombre total de pages (“Page 4 sur 12”) — la position dans la liste (début, milieu, fin) est compréhensible en navigation clavier/lecteur d’écran, sans avoir à deviner si une page est la dernière.
La page active porte aria-current="page".
Les séparateurs et points de suspension sont masqués aux lecteurs d’écran (aria-hidden).

À votre charge

Lien direct vers cette section

Annoncer le changement de page. La pagination ne gère pas le rechargement de contenu — c’est à vous d’annoncer le nouveau contenu chargé (via une live region ou un focus management) pour que l’utilisateur clavier sache que la page a changé.
current et total doivent rester cohérents. Une valeur current hors de [1, total] produit un état visuellement incohérent non corrigé par le composant.
current ne change que si vous le réassignez. Le focus et l’annonce aria-live suivent cette réassignation — faites-la une fois le nouveau contenu chargé, y compris en cas d’échec (voir la section Utilisation) : le composant reste en attente jusque-là.

Comportement responsive

Lien direct vers cette section

Le composant adapte son contenu automatiquement à la largeur du conteneur dans lequel il est positionné (pas celle du viewport) : Lorsque l’espace disponible n’est plus jugé suffisant, les numéros de page sont remplacés par un <select> de saut de page, peuplé du même jeu de pages qu’à largeur confortable — sauf en mode compact, qui ne bascule jamais et reste identique quelle que soit la largeur. Ce mode n’offre donc aucun filet de sécurité anti-débordement à largeur extrême (contrairement au mode adaptatif par défaut) : à vous de vérifier que le label et les boutons prev/next restent lisibles dans le contexte d’usage visé (ex. panneau de détail, drawer).

Utilisation

Lien direct vers cette section

Écoutez ar-pagination-page-change, chargez la page, puis réassignez current. Le composant reste en attente jusqu’à cette réassignation : en cas d’échec, réassignez la page actuelle. L’attribut pending sert à exprimer une attente qui ne passe pas par l’événement, comme un chargement initial.

pagination.addEventListener('ar-pagination-page-change', async (e) => {
    const ok = await loadPage(e.detail.to);
    pagination.current = ok ? e.detail.to : pagination.current;
});

Exemples

Lien direct vers cette section

Les exemples de cette page sont affichés avec le thème neutre du starter-kit.

Pour les besoins de la démo un script simule une réponse positive aux événements émis par le composant (voir Utilisation).

Par défaut

Lien direct vers cette section

Pagination sans attributs (valeurs par défaut du composant).

Voir le code

<ar-pagination></ar-pagination>

20 pages

Lien direct vers cette section

Pagination à 20 pages, page 10 active (milieu de la liste).

Voir le code

<ar-pagination current="10" total="20"></ar-pagination>

20 pages (current en début)

Lien direct vers cette section

Pagination à 20 pages, page 5 active (début de la liste).

Voir le code

<ar-pagination current="5" total="20"></ar-pagination>

20 pages (current en fin)

Lien direct vers cette section

Pagination à 20 pages, page 18 active (fin de la liste).

Voir le code

<ar-pagination current="18" total="20"></ar-pagination>

Mode compact

Lien direct vers cette section

Mode compact — uniquement précédent/suivant et un label de position, identique en mobile et desktop.

Voir le code

<ar-pagination compact current="4" total="12"></ar-pagination>

Démo interactive

Lien direct vers cette section

Manipulez les attributs pour voir le code et la preview se mettre à jour.

currenttotalcompactpending

<ar-pagination></ar-pagination>

Référence API

Lien direct vers cette section

Import

Lien direct vers cette section

Si vous utilisez l'autoloader, les composants détectés dans la pages sont chargés automatiquement, donc pas besoin de les importer individuellement.
Pour un import manuel, voici comment vous y prendre.

CDN

npm

Importez ce composant depuis le CDN.

<script type="module" src="https://unpkg.com/@ariane-ui/core/dist/components/pagination/index.js"></script>

Après avoir installé le paquet via npm, vous pouvez importer le composant ainsi :

import '@ariane-ui/core/dist/components/pagination/index.js';

Configuration

Lien direct vers cette section

Attributs et propriétés 4

Slots 2

Événements 2

currentreflète

Numéro de la page courante (commence à 1). Toute affectation compte, même vers la même valeur (`hasChanged` toujours vrai) : réassigner `current` est la réponse de l'application à `ar-pagination-page-change`, y compris pour signaler un échec (même page), et met fin à l'attente automatique.

Type number

totalreflète

Nombre total de pages.

Type number

compactreflète

Mode compact : uniquement les boutons précédent/suivant et un label de position ("Page X / Y"), navigation strictement séquentielle (pas de saut direct à une page). Rendu identique quelle que soit la largeur du conteneur (pas de repli en `<select>`).

Type booleanDéfaut false

pendingreflète

Attente d'une réponse, pilotée par l'application. Le composant attend déjà seul la réponse à chaque `ar-pagination-page-change` non annulé, jusqu'à la prochaine affectation de `current` : cet attribut sert à exprimer une attente qui ne passe pas par l'événement (chargement initial, rafraîchissement) et reste à la charge de l'application. Le composant ne le pose ni ne le retire jamais. Non bloquant : les interactions restent possibles. L'attente, manuelle ou automatique, pose `aria-busy="true"` sur la navigation, l'état `:state(pending)` et annonce l'attente au passage `false → true`.

Type booleanDéfaut false

prev-icon

Icône du bouton "Page précédente". Remplace le chevron SVG par défaut.

next-icon

Icône du bouton "Page suivante". Remplace le chevron SVG par défaut.

ar-pagination-page-changeannulabledetail : { id: string | undefined, from: number, to: number }

Émis avant le changement de page, à chaque interaction (clic page, précédent, suivant, sélection dans le `<select>` mobile). Annulable via `preventDefault()` : bloque l'interaction, `current` ne change pas. Contient `from` et `to`.

ar-pagination-page-changeddetail : { id: string | undefined, from: number, to: number }

Émis quand `current` a réellement changé (réassignation externe en réponse à `ar-pagination-page-change`, ou set programmatique indépendant). Non annulable. Contient `from` et `to`.

Personnalisation

Lien direct vers cette section

CSS Parts 18

CSS Custom States 1

CSS Custom Properties 2

Utilisez ::part(name) pour styler ces éléments depuis l'extérieur.
Certaines parts indiquent un rôle transverse, partagé avec d'autres composants — voir Personnalisation avancée.
Certaines parts portent un modificateur d'état (--) — voir Personnalisation avancée.

pagination

Racine du composant.

list

L'élément `<ul>` de la liste des pages.

item

Chaque `<li>` de la liste. Porte aussi le part d'état `item--current` sur le `<li>` de la page active.

item--current

Le `<li>` de la page courante (variante d'état de `item`).

link

Les `<a>` cliquables de chaque page. Personnalisable via `::part(link)` (fond, couleur, bordure, survol/pressé/focus).

control

Porté par `link` et `current` : élément interactif générique.

current

Le `<span>` de la page courante (non cliquable). Personnalisable via `::part(current)` (fond, couleur, bordure, épaisseur de trait).

Le bouton "Page précédente". Porte aussi le part combiné `nav-button`, partagé avec `next`.

Le bouton "Page suivante". Porte aussi le part combiné `nav-button`, partagé avec `prev`.

action-button

Porté par `prev` et `next` : bouton qui déclenche une action ponctuelle.

nav-button

Part combiné sur `prev`/`next`, pour cibler les deux boutons de navigation ensemble (ex. `::part(nav-button)` pour un style commun distinct des numéros de page).

nav-button--disabled

Variante d'état de `nav-button` posée sur `prev`/`next` quand désactivé (page 1 ou dernière page).

ellipsis

Le `<span>` d'ellipse (`...`) entre deux groupes de pages, non interactif.

page-select

Le `<li>` englobant le `<select>` de saut de page, affiché à la place de la liste de pages quand l'espace disponible ne permet plus d'afficher de numéros (palier minimal).

select

L'élément `<select>` de saut de page. Personnalisable via `::part(select)` (apparence). Conserve l'apparence native du navigateur (flèche incluse) par défaut.

field

Porté par `select` : élément qui reçoit une saisie. Sous-rôle standard de `field` (avec `input`, cf. ar-datepicker), réutilisable par tout futur composant avec une liste déroulante.

page-label

Le `<li>` englobant le label de position en mode compact (`compact`), affiché à la place de la liste de pages. Sur le modèle de `page-select`.

label

Le `<span>` du label de position en mode compact ("Page X / Y"), non cliquable et masqué aux lecteurs d'écran (`aria-hidden`, l'information équivalente est déjà portée par le landmark et le texte accessible (sr-only) de prev/next). Personnalisable via `::part(label)`.

Utilisez le sélecteur :state(name) sur le tag pour styler ce composant en fonction de son état.
Composable avec ::part() pour cibler un élément interne (ar-pagination:state(name)::part(x)).
Sous Chrome et Edge 125, l'état est exposé avec le préfixe -- (:--name) : voir Compatibilité.

:state(pending)

Une réponse est attendue : un utilisateur a demandé à changer de page ou l'application a posé manuellement l'attribut `pending`.

--ar-pagination-button-size

Hauteur et largeur minimales des boutons/pages (repli interne `2.5rem`, WCAG 2.5.8).

--ar-pagination-transition-duration

Durée de la transition (fond/couleur) au survol/pressé/focus de prev/next/page.

Traduction

Lien direct vers cette section

La langue de ce composant suit l'attribut lang de la page (<html lang>).
Vous pouvez appliquer une langue différente à une instance donnée en posant l'attribut lang directement dessus.
Voir la page Traductions pour le détail du mécanisme et la liste des traductions disponibles.

lang étant un attribut HTML natif, il n'apparaît pas dans le tableau « Attributs & Propriétés ».