Champ de saisie (Input)

Utilisez les champs de saisie pour collecter une information textuelle courte ou longue.

attention

Ce composant nécessite une licence Pro valide en production.

Information	Valeur
Niveau	Pro
Composants Twig	dsfr:input, dsfr:textarea

Usage

• Le composant normalise les identifiants HTML.
• Utilisez dsfr:textarea pour les contenus multi-lignes.

Modes d'utilisation

Exemple principal

Champ de saisie · exemple principal

<twig:dsfr:input
  id="email"
  name="email"
  type="email"
  label="Adresse électronique"
  hint="Format attendu : nom@example.fr"
/>
<twig:dsfr:textarea
  id="message"
  name="message"
  label="Message"
  rows="5"
/>

Composition

Cette page expose aussi les sous-composants publics suivants : dsfr:textarea. 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 rows 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:input :rows="rows" />

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:input
  id="champ-de-saisie-example"
  class="fr-mt-2w"
  data-controller="champ-de-saisie"
/>

API publique

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

Configuration

Option	Type	Défaut / requis	Valeurs et usage
id	string	Selon composant	Identifiant HTML, normalisé et utilisé par aria-controls quand nécessaire.
label	string	Requis	Libellé visible du contrôle.
type	enum	text	text, email, password, search, tel, url, number, date, time, month, week
name / value / placeholder	string|null	null	Attributs standards du champ.
hint	string|null	null	Texte d’aide DSFR.
error	string|null	null	Message d’erreur, active l’état erreur.
valid	string|null	null	Message de validation, active l’état valide.
required	bool	false	Rend le champ obligatoire côté HTML.
disabled	bool	false	Désactive le contrôle. Accepte aussi 0/1 ou chaînes booléennes.
rows	int|string	6 pour dsfr:textarea	Nombre de lignes pour la zone de texte.

Guide d'intégration

Question	Réponse
Famille DSFR	Formulaire
Quand l'utiliser	Quand l’interface collecte, valide ou soumet une donnée utilisateur.
Quand éviter	Pour afficher une information non modifiable : préférez un composant de contenu ou de feedback.
API publique	Utilisez uniquement les composants Twig listés sur cette page : dsfr:input, dsfr:textarea.
Documentation DSFR	Consultez aussi la bibliothèque officielle : Système de Design de l'État.

Champ de saisie : composition Twig et données rows

Variantes de champ de saisie

• types métier via type pour adapter le sens visuel et sémantique.
• état désactivé avec disabled quand l’action existe mais n’est pas disponible.
• états de validation avec error et valid, sans construire les classes à la main.

Points de contrôle propres à ce composant

• Le composant normalise les identifiants HTML.
• Utilisez dsfr:textarea pour les contenus multi-lignes.
• Vérifiez un cas vide, un cas avec plusieurs entrées et un cas avec données dynamiques pour rows.
• Testez la composition avec dsfr:textarea sans copier les templates internes.
• Vérifiez les états erreur, succès et neutre avec les messages réellement liés au champ.

Accessibilité formulaire

• Chaque champ doit avoir un label, legend ou titre de groupe compréhensible.
• Les aides et erreurs doivent rester reliées au champ avec les identifiants générés.
• Utilisez required, disabled, error et valid pour refléter le vrai statut métier.

Intégration Symfony/Twig pour dsfr:input

• Passez rows avec la syntaxe : pour conserver le type tableau : :rows="rows".
• Composez avec les sous-composants publics dsfr:textarea quand le rendu doit être plus précis que les props.
• Ajoutez vos attributs applicatifs (data-controller, data-action, aria-*, class) sur dsfr:input quand ils concernent son nœud racine.
• Gardez des id prévisibles pour dsfr:input, surtout dans les listes ou formulaires répétés.

Checklist de recette

• label visible ou accessible
• message erreur lu par technologie d’assistance
• valeurs conservées après erreur de validation
• 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 rows ne sont pas prises en compte	Ajoutez : devant la prop Twig : :rows.
Les classes DSFR semblent incomplètes	Utilisez les props du composant plutôt que des classes ajoutées à la main.
Un panneau, menu ou état actif ne fonctionne pas	Vérifiez que le JavaScript DSFR est chargé et que les identifiants HTML sont uniques.
Le composant rend en local mais pas en production	Vérifiez la licence avec php bin/console dsfr:license:validate.