Champ

Le champ de saisie est l'élément de base de tout formulaire. Il supporte différents types de données, des messages contextuels (helper, erreur) et une icône pour renforcer la lisibilité. Son état communique la disponibilité et la validité de la valeur saisie.

Types

Le champ accepte tous les types HTML natifs via la prop type. Par défaut text. Utiliser le type approprié permet au navigateur d'afficher le bon clavier sur mobile et d'activer les validations natives.

text Défaut. Saisie libre : nom, prénom, titre…
email Adresse e-mail. Active la validation native et le clavier e-mail sur mobile.
password Masque la valeur. Le navigateur propose de sauvegarder.
<twig:Field>   <twig:Field:Label for="email">Email</twig:Field:Label>   <twig:Input id="email" type="email" placeholder="vous@sudalys.fr" /> </twig:Field>

États

Chaque état a un rôle précis : required signale une obligation, helper guide l'utilisateur, error l'informe d'une valeur invalide, disabled verrouille le champ. Ne jamais simuler ces états par du CSS inline, toujours passer par les props.

Votre nom complet tel qu'il apparaîtra.

required Affiche un * rouge dans le label et pose required sur l'input.
helper Message d'aide sous le champ. Remplacé par error si les deux sont présents.
error Bordure rouge, message d'erreur avec icône, aria-invalid="true".
disabled Fond grisé, curseur interdit, opacité 60 %. Valeur non soumise au formulaire.
<twig:Field>   <twig:Field:Label for="nom">Nom</twig:Field:Label>   <twig:Input id="nom" />   <twig:Field:Description>Votre nom complet.</twig:Field:Description> </twig:Field> &nbsp; <twig:Field>   <twig:Field:Label for="email" required>Email</twig:Field:Label>   <twig:Input id="email" type="email" aria-invalid />   <twig:Field:Error>Email invalide.</twig:Field:Error> </twig:Field> &nbsp; <twig:Field>   <twig:Field:Label for="ref">Référence</twig:Field:Label>   <twig:Input id="ref" disabled /> </twig:Field>

Avec icône

Une icône peut être positionnée à gauche (défaut) ou à droite du champ. Elle est purement décorative et marquée aria-hidden. Le padding de l'input s'adapte automatiquement pour ne pas chevaucher le texte.

align="inline-start" Icône avant le texte saisi (gauche).
align="inline-end" Icône après le texte saisi (droite).
<twig:Field>   <twig:Field:Label for="search">Recherche</twig:Field:Label>   <twig:InputGroup>     <twig:InputGroup:Addon align="inline-start">{{ ux_icon('bi:search') }}</twig:InputGroup:Addon>     <twig:InputGroup:Input id="search" type="text" placeholder="Rechercher..." />   </twig:InputGroup> </twig:Field>

Les icônes utilisent le système UX Icons. Préfixe bi: pour Bootstrap Icons, material-symbols: pour Material. Voir la liste complète sur ux.symfony.com/icons.

API du composant

Le champ est composé de plusieurs sous-composants autonomes. Chacun accepte les attributs HTML natifs via {{ attributes }}.

<twig:Field>

PropTypeDéfautValeurs acceptéesDescription
orientation string 'vertical' vertical horizontal responsive Disposition du label et du champ. responsive bascule en horizontal à partir de @md.

<twig:Field:Label>

PropTypeDéfautValeurs acceptéesDescription
required bool false true false Affiche un * rouge après le libellé. Passer aussi required sur twig:Input pour la validation native.
for string Identifiant de l'input Attribut HTML for. Doit correspondre à l'id de twig:Input.

<twig:Input>

Attribut HTMLTypeDéfautDescription
id string Lie l'input à son label via for. Doit être unique dans la page.
type string 'text' Type HTML : text email password search tel…
placeholder string Texte indicatif affiché quand le champ est vide.
value string Valeur pré-remplie.
disabled bool Verrouille le champ. Fond grisé, curseur interdit.
required bool Active la validation native du navigateur.
aria-invalid bool Passe la bordure en rouge. À utiliser avec twig:Field:Error.

Sous-composants de contenu

ComposantRôleProps
twig:Field:Description Message d'aide affiché sous le champ (texte secondaire).
twig:Field:Error Message d'erreur affiché sous le champ (texte rouge). À combiner avec aria-invalid sur l'input.

<twig:InputGroup> champ avec icône

ComposantPropValeursDescription
twig:InputGroup Wrapper qui regroupe l'icône et l'input dans un même bloc avec focus ring unifié.
twig:InputGroup:Addon align inline-start inline-end Conteneur pour l'icône. inline-start = gauche, inline-end = droite.
twig:InputGroup:Input Input adapté au contexte de groupe (sans bordure propre, sans focus ring individuel).

Do & Don't

Do (À faire)
  • Donner un id unique à twig:Input et le lier via for sur twig:Field:Label
  • Utiliser twig:Field:Error + aria-invalid sur l'input après validation serveur ou client
  • Ajouter twig:Field:Description pour préciser le format attendu
  • Choisir le type HTML adapté à la donnée saisie
  • Marquer required sur le label et sur l'input pour tous les champs obligatoires
Don't (À éviter)
  • Écrire un <input> manuellement avec des classes ds-field__*
  • Simuler l'état d'erreur avec une bordure en CSS inline au lieu de aria-invalid
  • Afficher twig:Field:Description et twig:Field:Error simultanément
  • Omettre twig:Field:Label en comptant sur le placeholder pour identifier le champ
  • Utiliser une icône pour véhiculer une information essentielle (invisible pour les lecteurs d'écran)

Règles

Règle

Toujours utiliser <twig:Field>. Ne jamais écrire un <input> manuellement avec des classes ds-field__*.

Règle

Un label est obligatoire pour l'accessibilité. Le placeholder seul n'est pas un substitut : il disparaît dès que l'utilisateur commence à saisir.

Règle

twig:Field:Error doit toujours être accompagné d'un message explicite expliquant pourquoi la valeur est invalide.

Règle

Ne jamais désactiver un champ sans expliquer à l'utilisateur (via twig:Field:Description ou une info-bulle) pourquoi il ne peut pas saisir.

logo sudalys Sudalys 2026 Version 0.0.1