Fil d’Ariane (Breadcrumb)

Utilisez le fil d’Ariane pour situer la page dans l’arborescence du site.

info

Ce composant est inclus dans l’offre Community.

Information	Valeur
Niveau	Community
Composants Twig	dsfr:breadcrumb, dsfr:breadcrumb:item

Usage

• La page courante porte aria-current="page".
• dsfr:breadcrumb:item est Pro pour les compositions avancées.

Modes d'utilisation

Exemple principal

Fil d’Ariane · exemple principal

<twig:dsfr:breadcrumb>
  <twig:dsfr:breadcrumb:item label="Accueil" href="/" />
  <twig:dsfr:breadcrumb:item label="Dossiers" href="/dossiers" />
  <twig:dsfr:breadcrumb:item label="Dossier 2026-042" current />
</twig:dsfr:breadcrumb>

<twig:dsfr:breadcrumb :items="[
  {label: 'Accueil', href: '/'},
  {label: 'Dossiers', href: '/dossiers'},
  {label: 'Dossier 2026-042', current: true}
]" />

Composition

Cette page expose aussi les sous-composants publics suivants : dsfr:breadcrumb:item. Utilisez-les quand vous devez contrôler précisément la structure Twig au lieu de passer un tableau de données.

astuce

Préférez les sous-composants publics aux include, macros ou copies de templates internes. Cela garde votre code aligné avec les évolutions du bundle.

Données

La prop items accepte un tableau PHP/Twig. En Twig, préfixez la prop par : pour transmettre une vraie structure de données.

Syntaxe typée Twig Component

{# Le préfixe : garde le type tableau/booléen/numérique. #}
<twig:dsfr:breadcrumb :items="items" />

Attributs HTML

Ajoutez vos attributs applicatifs directement sur le composant quand ils concernent le nœud racine rendu par le template.

Attributs pass-through

<twig:dsfr:breadcrumb
  id="fil-d-ariane-example"
  class="fr-mt-2w"
  data-controller="fil-d-ariane"
/>

API publique

Composant	Rôle
dsfr:breadcrumb	Composant principal de cette page.
dsfr:breadcrumb:item	Sous-composant public utilisable en composition Twig.

Configuration

Option	Type	Défaut / requis	Valeurs et usage
collapsibleId	string	breadcrumb	Identifiant du panneau mobile.
buttonLabel	string	Voir le fil d’Ariane	Libellé du bouton mobile.
items	array|string	[]	Items { label, href?, current? }.

Guide d'intégration

Question	Réponse
Famille DSFR	Navigation
Quand l'utiliser	Quand l’usager doit se repérer, changer de section ou parcourir une liste de pages.
Quand éviter	Pour déclencher une action métier immédiate : utilisez plutôt un bouton.
API publique	Utilisez uniquement les composants Twig listés sur cette page : dsfr:breadcrumb, dsfr:breadcrumb:item.
Documentation DSFR	Consultez aussi la bibliothèque officielle : Système de Design de l'État.

Fil d’Ariane : composition Twig et données items

Variantes de fil d’ariane

• fil d’ariane avec attributs HTML pass-through pour id, class, data-* et aria-* quand le template le permet.

Points de contrôle propres à ce composant

• La page courante porte aria-current="page".
• dsfr:breadcrumb:item est Pro pour les compositions avancées.
• Vérifiez un cas vide, un cas avec plusieurs entrées et un cas avec données dynamiques pour items.
• Testez la composition avec dsfr:breadcrumb:item sans copier les templates internes.

Accessibilité navigation

• Le libellé de navigation doit être explicite avec ariaLabel ou un titre visible.
• La page courante doit être indiquée avec active, current ou aria-current selon le composant.
• Les panneaux contrôlés par JavaScript DSFR doivent avoir des id uniques et stables.

Intégration Symfony/Twig pour dsfr:breadcrumb

• Passez items avec la syntaxe : pour conserver le type tableau : :items="items".
• Composez avec les sous-composants publics dsfr:breadcrumb:item quand le rendu doit être plus précis que les props.
• Ajoutez vos attributs applicatifs (data-controller, data-action, aria-*, class) sur dsfr:breadcrumb quand ils concernent son nœud racine.

Checklist de recette

• navigation clavier complète
• état actif visible
• liaison aria-controls vers un élément existant
• rendu vérifié en thème clair et sombre ;
• rendu vérifié sur mobile, tablette et desktop ;
• aucune erreur dans le profiler DSFR ni dans l'inspecteur d'accessibilité du navigateur.

Erreurs fréquentes

Symptôme	Correction
Les données items ne sont pas prises en compte	Ajoutez : devant la prop Twig : :items.
Les classes DSFR semblent incomplètes	Utilisez les props du composant plutôt que des classes ajoutées à la main.