Lien (Link)

Utilisez un lien DSFR pour une navigation textuelle ou un lien externe.

info

Ce composant est inclus dans l’offre Community.

Information	Valeur
Niveau	Community
Composants Twig	dsfr:link, dsfr:links:group

Usage

• Un lien externe ajoute les attributs de sécurité.
• Les icônes peuvent être placées à gauche ou à droite.

Modes d'utilisation

Exemple principal

Lien · exemple principal

<twig:dsfr:links:group inline size="sm">
  <twig:dsfr:link
  label="Consulter la documentation officielle"
  href="https://www.systeme-de-design.gouv.fr"
  external
  />
  <twig:dsfr:link label="Aide" href="/aide" />
</twig:dsfr:links:group>

Composition

Cette page expose aussi les sous-composants publics suivants : dsfr:links:group. 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.

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:link
  id="lien-example"
  class="fr-mt-2w"
  data-controller="lien"
/>

API publique

Composant	Rôle
dsfr:link	Composant principal de cette page.
dsfr:links:group	Sous-composant public utilisable en composition Twig.

Configuration

Option	Type	Défaut / requis	Valeurs et usage
label	string	Requis	Libellé visible du contrôle.
href	string|null	Selon composant	URL de destination. Les URL sont normalisées.
external	bool	false	Lien externe avec attributs de sécurité.
size	enum	md	md, sm, lg
icon	string|null	null	Classe d’icône DSFR, par exemple fr-icon-save-line.
iconPlace	enum	left ou right	left, right
download	bool	false	Active la variante téléchargement.
dsfr:links:group	props	size, inline	Groupe plusieurs liens avec les classes DSFR adaptées.

Guide d'intégration

Question	Réponse
Famille DSFR	Interaction
Quand l'utiliser	Quand l’usager déclenche une action, ouvre une ressource, filtre une vue ou manipule une interaction ponctuelle.
Quand éviter	Pour structurer une page complète ou afficher un statut durable : utilisez plutôt un composant de contenu ou de feedback.
API publique	Utilisez uniquement les composants Twig listés sur cette page : dsfr:link, dsfr:links:group.
Documentation DSFR	Consultez aussi la bibliothèque officielle : Système de Design de l'État.

Lien : composition avec 1 sous-composant

Variantes de lien

• tailles disponibles via size quand le DSFR expose une variante compacte ou large.
• icône DSFR avec icon et placement contrôlé par la prop dédiée.

Points de contrôle propres à ce composant

• Un lien externe ajoute les attributs de sécurité.
• Les icônes peuvent être placées à gauche ou à droite.
• Testez la composition avec dsfr:links:group sans copier les templates internes.
• Contrôlez le rendu lien/action selon la présence de href et le libellé annoncé au clavier.
• Contrôlez l’icône, son placement et le libellé accessible quand l’icône porte seule l’action.

Accessibilité interaction

• Le libellé d’action doit rester compréhensible hors contexte.
• Les icônes seules nécessitent un libellé accessible.
• Les actions indisponibles doivent utiliser disabled ou un état équivalent documenté.

Intégration Symfony/Twig pour dsfr:link

• Composez avec les sous-composants publics dsfr:links:group quand le rendu doit être plus précis que les props.
• Ajoutez vos attributs applicatifs (data-controller, data-action, aria-*, class) sur dsfr:link quand ils concernent son nœud racine.

Checklist de recette

• focus clavier visible
• libellé accessible vérifié
• état hover/focus/disabled cohérent
• 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 classes DSFR semblent incomplètes	Utilisez les props du composant plutôt que des classes ajoutées à la main.