Combobox
À quoi il sert
Combobox est un champ texte qui propose une liste de suggestions, filtrée à chaque saisie.
Quand l’utiliser
- Choisir dans une longue liste connue, comme des pays ou des villes.
- Accepter aussi une saisie libre : le formulaire envoie le texte du champ.
Quand ne pas l’utiliser
- Pour quelques choix seulement : Select ou Choice les montrent sans saisie.
- Pour une recherche qui interroge un serveur : le filtre porte sur les options rendues.
- Pour envoyer un identifiant distinct du libellé : le champ envoie le libellé.
Exemples
Tapez quelques lettres, puis choisissez avec les flèches.
- Allemagne
- Belgique
- Estonie
- Espagne
- Égypte
- France
- Italie
- Japon
- Allemagne
- Belgique
- Estonie
- Espagne
- Égypte
- France
- Italie
- Japon
<Combobox
id="pays"
name="pays"
label="Pays"
hint="Tapez quelques lettres."
options={[
{ value: 'fr', label: 'France' },
{ value: 'ee', label: 'Estonie' },
]}
noResultsLabel="Aucun pays ne correspond."
countLabel="{count} pays proposés."
/>Variantes
Saisie libre acceptée : Lille n’est pas dans la liste.
- Bordeaux
- Lyon
- Nantes
- Saint-Étienne
Accessibilité
Clavier
- Flèche bas et flèche haut ouvrent la liste, déplacent l’option active et bouclent (motif APG Combobox).
- Entrée écrit l’option active dans le champ et ferme la liste.
- Échap ferme la liste ; un second Échap vide le champ.
- Tab ferme la liste sans valider ; Début et Fin restent au curseur du champ.
- Le focus reste dans le champ : l’option active passe par aria-activedescendant.
Lecteur d’écran
- Le champ a le rôle combobox, son nom vient du <label for> (WCAG 4.1.2).
- aria-expanded indique si la liste est ouverte ; aria-controls la désigne.
- Une zone role="status" annonce le nombre de suggestions (WCAG 4.1.3).
- Rendu non testé avec VoiceOver, NVDA ni JAWS : à vérifier avant usage critique.
Garanti par le composant
- Sans script, le champ reste un <input list> relié à un <datalist> natif.
- La saisie filtre sans sélectionner d’option d’elle-même (aria-autocomplete="list").
- Le filtre ignore la casse et les accents : « ege » trouve « Égypte ».
- Options d’au moins --pp-size-target-min de haut (WCAG 2.5.8).
- L’option active est soulignée en plus du fond coloré (WCAG 1.4.1).
- La liste a une hauteur bornée et défile ; l’option active défile dans la vue.
À la charge de l’intégrateur
- Fournir label, noResultsLabel et countLabel dans la langue du site.
- Avec required, fournir requiredLabel pour signaler le champ obligatoire en texte (WCAG 3.3.2).
- Avec invalid, afficher le message d’erreur près du champ (WCAG 3.3.1).
- Servir le script en fichier externe : la CSP doit autoriser script-src 'self'.
Propriétés
| Propriété | Type | Défaut | Description |
|---|---|---|---|
| label (obligatoire) | string | — | Libellé visible du champ ; nomme aussi la liste de suggestions. |
| name (obligatoire) | string | — | Nom envoyé avec le formulaire (le texte du champ). |
| id (obligatoire) | string | — | Id du champ ; dérive `<id>-listbox`, `<id>-datalist` et `<id>-option-<n>`. |
| options (obligatoire) | Option[] | — | Suggestions proposées : `{ value, label }`. |
| value | string | — | Valeur initiale : `value` d'une option (son libellé est affiché) ou texte libre. |
| hint | string | — | Indication sous le libellé, reliée par `aria-describedby`. |
| noResultsLabel (obligatoire) | string | — | Annonce quand aucune suggestion ne correspond, par exemple « Aucun résultat ». |
| countLabel (obligatoire) | string | — | Annonce du nombre de suggestions, avec `{count}`, par exemple « {count} résultats ». |
| required | boolean | false | Saisie obligatoire (`required`). |
| requiredLabel | string | — | Texte accolé au libellé si `required`, par exemple « obligatoire ». |
| invalid | boolean | false | Pose `aria-invalid="true"` sur le champ. |
| class | string | — | Réservé au placement du composant dans son parent. |
Jetons utilisés
--pp-color-accent--pp-color-bg--pp-color-control--pp-color-fg--pp-color-muted--pp-color-on-accent--pp-color-status-failed--pp-color-surface--pp-font-line-height-body--pp-font-size-0--pp-radius-control--pp-size-control-height--pp-size-focus-offset--pp-size-focus-width--pp-size-rule--pp-size-target-min--pp-space-2xl--pp-space-3xl--pp-space-3xs--pp-space-xs--pp-z-overlay
Preuves et décisions
- APG : Combobox with List Autocomplete
- WCAG 4.1.2 Nom, rôle et valeur
- WCAG 4.1.3 Messages d’état
- WCAG 2.5.8 Taille de la cible (minimum)
- WCAG 1.4.1 Utilisation de la couleur
- Tests : packages/astro/test/Combobox.test.ts
- Tests : packages/astro/test/combobox.behavior.test.ts