Bouton (Button)

Utilisez un bouton pour déclencher une action ou un lien d’action stylé DSFR.

info

Ce composant est inclus dans l’offre Community.

Information	Valeur
Niveau	Community
Composants Twig	dsfr:button, dsfr:button:group

Usage

• Avec href, le composant rend un lien.
• Sans href, il rend un bouton type="button".
• dsfr:button:group est Pro.

Modes d'utilisation

Exemple principal

Bouton · exemple principal

<twig:dsfr:button:group inline iconPlace="left">
  <twig:dsfr:button label="Enregistrer" icon="fr-icon-save-line" />
  <twig:dsfr:button label="Annuler" variant="secondary" />
</twig:dsfr:button:group>

Composition

Cette page expose aussi les sous-composants publics suivants : dsfr:button: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:button
  id="bouton-example"
  class="fr-mt-2w"
  data-controller="bouton"
/>

API publique

Composant	Rôle
dsfr:button	Composant principal de cette page.
dsfr:button: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.
variant	enum	primary	primary, secondary, tertiary, tertiary-no-outline
size	enum	md	md, sm, lg
icon	string|null	null	Classe d’icône DSFR, par exemple fr-icon-save-line.
iconPlace	enum	left si icône seule absente	left, right
iconOnly	bool	false	Rend un bouton icône seule.
disabled	bool	false	Désactive le contrôle. Accepte aussi 0/1 ou chaînes booléennes.
fullWidth	bool	false	Largeur complète.
htmlType	string	button	Type HTML du bouton : button, submit, reset.
dsfr:button:group	props	align, size, inline, equisized, reverse, iconPlace	Options de groupe.

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:button, dsfr:button:group.
Documentation DSFR	Consultez aussi la bibliothèque officielle : Système de Design de l'État.

Bouton : composition avec 1 sous-composant

Variantes de bouton

• 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.
• état désactivé avec disabled quand l’action existe mais n’est pas disponible.

Points de contrôle propres à ce composant

• Avec href, le composant rend un lien.
• Sans href, il rend un bouton type="button".
• dsfr:button:group est Pro.
• Testez la composition avec dsfr:button: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:button

• Composez avec les sous-composants publics dsfr:button:group quand le rendu doit être plus précis que les props.
• Ajoutez vos attributs applicatifs (data-controller, data-action, aria-*, class) sur dsfr:button 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.