Aller au contenu
SkillCodex
Menu

Listbox

Liste d'options

Un widget composite d'options nommées qui accepte une ou plusieurs sélections et peut être autonome ou servir de surface contextuelle à une combobox.

Essayer le composant
Repères, sources et actions
Sources et révision
Mis à jour le
Version
v1.0.26 · r2
Sources
5 sources
Statut
Publié
Consulter les sources

Tu as peut-être cherché : garder tous les choix visibles dans une boîteune liste sélectionnable qui ne se replie pasutiliser les flèches dans les options visibles

Toutes les formulations
Enregistrer et partager

Reconnaître

Choisir dans une liste

Essayer

La personne choisit-elle une valeur native, filtre-t-elle en saisissant ou navigue-t-elle dans une liste ?

Liste d'options

Contexte commun aux essais

Un formulaire demande à l'utilisateur de choisir une valeur dans un ensemble d'options connu avant de continuer.

Liste d'options

Mission

Liste de choix visible - Listbox

Focaliser la liste, atteindre 30 derniers jours avec les flèches, sélectionner et vérifier que l'état reste visible.

7 derniers jours

Résultat de l’essai

7 derniers jours est l'unique option sélectionnée. La liste reste visible.

Étape 1 sur 3

Essayer

Manipule le composant. Le résultat de ton essai apparaît juste au-dessus. Avance à ton rythme.

Comportement et cas limite
À observer
Les quatre périodes restent visibles ; la ligne sélectionnée est mise en évidence et reprise dans le statut. Cet exemple natif ne sépare pas un état actif d'un état validé.
Cas limite
Une période personnalisée désactivée est annoncée, ignorée selon le modèle clavier et jamais confondue avec la valeur choisie.

Ce que cet essai montre

Listbox est le widget d'options composite, autonome ou contextuel, à sélection simple ou multiple ; Select est un contrôle de formulaire natif, tandis que Combobox est le contrôle de valeur qui possède ou contrôle une surface associée.

Lequel convient à ton besoin ?

Liste d'options

Une ou plusieurs valeurs sont choisies dans un ensemble composite d'options nommé

Liste de sélection

Choisir une ou plusieurs valeurs connues dans une liste prédéfinie

Quel composant utilises-tu ici ?
Différence et sources

Listbox est le widget d'options composite, autonome ou contextuel, à sélection simple ou multiple ; Select est un contrôle de formulaire natif, tandis que Combobox est le contrôle de valeur qui possède ou contrôle une surface associée.

Consulter les sources

    Parties du spécimen

    Sélectionne un repère numéroté sur le schéma, ou utilise la liste ci-dessous, pour afficher son rôle. Le schéma montre l'état représentatif du concept.

    Libellé

    Le texte persistant qui nomme un contrôle ou un champ.

    Position dans l’atlas

    Carte relationnelle

    Repère le chapitre, les concepts proches et la prochaine décision utile.

    • Chapitre

      Choisir dans une liste

      Liste d'options appartient à ce groupe de concepts comparés.

    • Ne pas confondre

      Liste de sélection

      Choisis Liste d’options si les options exigent un rendu personnalisé, restent visibles ou permettent une sélection multiple avec des raccourcis clavier que tu contrôles. Choisis Liste de sélection si un ensemble connu de valeurs tient dans un champ de formulaire simple et que le natif suffit.

      Comparer cette paire
    • Ne pas confondre

      Combobox

      Choisis Liste d’options si les options restent visibles dans la page ou si plusieurs peuvent être sélectionnées à la fois. Choisis Combobox si l’utilisateur saisit ou filtre pour atteindre une valeur et que les options n’apparaissent qu’à la demande.

      Comparer cette paire
    • Prochaine étape

      Compare les concepts du chapitre avant de retenir une implémentation.

      Ouvrir le chapitre

    Avec tes mots

    Comprendre

    Ce que les gens décrivent

    Alias documentés : liste d'options, liste de sélection, liste multisélection

    • garder tous les choix visibles dans une boîte
    • une liste sélectionnable qui ne se replie pas
    • utiliser les flèches dans les options visibles
    • choisir un élément dans une liste permanente
    • une boîte d'options avec la ligne choisie en évidence
    • afficher plusieurs choix à la fois pour comparer

    Choisir

    À utiliser quand

    • Une ou plusieurs valeurs sont choisies dans un ensemble composite d'options nommé
    • Le clavier bénéficie d'une navigation rapide entre options

    À éviter quand

    • L'espace manque et un Select natif suffit
    • Les éléments sont des commandes plutôt que des valeurs

    Comparer

    Comparer les concepts proches

    Checklist de vérification

    Essaie ces gestes dans le lab, puis vérifie les mêmes comportements dans le résultat de ton agent. Adapte les noms d’exemple à ton interface.

    1. 1. À faire

      Atteins la liste visible avec Tab et parcours les options avec les flèches.

      Résultat attendu

      La liste forme un seul arrêt au clavier ; l’option active est visible et suit le comportement de sélection annoncé.

    2. 2. À faire

      Choisis deux options à la suite, avec la commande indiquée pour la sélection multiple si elle est proposée.

      Résultat attendu

      Une liste à choix unique garde une seule valeur sélectionnée ; une liste à choix multiple ne modifie que les sélections voulues.

    3. 3. À faire

      Essaie une option indisponible, puis appuie sur Tab pour quitter la liste.

      Résultat attendu

      L’option indisponible ne peut pas devenir une valeur sélectionnée, et Tab atteint le prochain élément sans t’enfermer dans la liste.

    Contrat complet
    1. 1Les options appartiennent à une liste nommée, autonome ou contextuelle
    2. 2La relation entre focus et sélection est déclarée, notamment si la sélection suit le focus
    3. 3Les flèches, Début et Fin sont cohérents
    4. 4Le mode de sélection est explicite

    Comprendre → Reconnaître → Choisir → Comparer

    Pack pour ton agent

    Instructions pré-écrites à coller dans ton agent. Copier n’exécute rien.

    Implémenter correctement

    Construis Liste d’options sans casser son comportement

    # Implémenter Liste d’options dans ton agent
    
    ## Objectif
    Implémente Liste d’options pour ce comportement vérifié : Un widget composite d’options nommées qui accepte une ou plusieurs sélections et peut être autonome ou servir de surface contextuelle à une combobox.
    
    ## Prérequis
    - Inspecte d’abord le dépôt, le design system et les tests existants.
    - Préserve les changements sans rapport et borne les fichiers modifiés.
    - Confirme que Liste d’options répond au besoin avant de coder.
    
    ## Comportement requis
    - Les flèches parcourent les options selon le modèle déclaré du contrôle ; les états de focus et de sélection sont exposés de façon cohérente, y compris lorsque la sélection suit le focus.
    - Le contrôle expose si une ou plusieurs valeurs peuvent être sélectionnées et met à jour chaque état sélectionné de façon cohérente.
    
    ## États à couvrir
    - Période par défaut sélectionnée
    - 30 derniers jours sélectionnés
    
    ## Accessibilité
    - Rôle ARIA : listbox > option
    - Le contrôle principal ou la région nommée pour Liste d’options possède un nom accessible stable issu d’un texte visible ou d’un libellé programmatique explicite ; le placeholder et l’infobulle ne servent pas de nom.
    - Le select natif affichant plusieurs lignes forme un seul arrêt de tabulation. Dans cet exemple à sélection simple, la sélection suit le focus clavier : états actif et sélectionné évoluent ensemble ; une listbox personnalisée doit déclarer son propre modèle.
    - Dans cet exemple autonome, quitter avec Tab conserve la valeur sélectionnée ; lorsqu’une listbox est contextuelle, sa fermeture est coordonnée par le contrôle propriétaire.
    - Le nom de la liste, ses quatre options, la sélection, l’état désactivé et le mode simple de cet exemple sont exposés par la sémantique native.
    - Tab entre une fois dans le contrôle composite
    - Dans cet exemple natif à sélection simple, les flèches mettent la sélection à jour avec le focus
    - Cet exemple n’a pas de commande de validation séparée
    - Les touches Début et Fin prises en charge par la plateforme atteignent les limites
    
    ## Quand ne pas utiliser
    - L’espace manque et un Select natif suffit
    - Les éléments sont des commandes plutôt que des valeurs
    
    ## Critères d’acceptation
    - Les options appartiennent à une liste nommée, autonome ou contextuelle
    - La relation entre focus et sélection est déclarée, notamment si la sélection suit le focus
    - Les flèches, Début et Fin sont cohérents
    - Le mode de sélection est explicite
    
    ## Garde-fous
    - Montre d’abord les changements envisagés avant toute action externe.
    - Ne publie, n’envoie, ne supprime, ne paie et ne modifie aucun état distant sans autorisation explicite.
    - Préserve les changements sans rapport et arrête-toi si le périmètre devient ambigu.
    
    ## Format de sortie
    - Résultat obtenu ou verdict.
    - Fichiers ou actions concernés.
    - Vérifications exécutées et preuves observables.
    - Blocages ou limites restantes.
    
    • Web platform
    • Prérequis · Accès au dépôt, au design system et aux tests
    Pourquoi ça marche
    • Le besoin est relié au comportement canonique avant toute décision technique.
    • Les états, l’accessibilité et les non-objectifs empêchent une implémentation seulement visuelle.
    • Les critères d’acceptation et le format de sortie rendent la vérification observable.

    À essayer ensuite

    Vérifie Liste d’options sur un parcours réel

    # Vérifier Liste d’options après l’implémentation
    
    ## Objectif
    Audite l’implémentation de Liste d’options au regard de son comportement, de ses états et de ses exigences d’accessibilité sans la modifier automatiquement.
    
    ## Contrôles
    - Rejoue le plus petit parcours représentatif.
    - Contrôle le clavier, le focus, le nom accessible et les annonces.
    - Relie chaque écart à un critère d’acceptation précis.
    
    ## Garde-fous
    - Montre d’abord les changements envisagés avant toute action externe.
    - Ne publie, n’envoie, ne supprime, ne paie et ne modifie aucun état distant sans autorisation explicite.
    - Préserve les changements sans rapport et arrête-toi si le périmètre devient ambigu.
    
    ## Format de sortie
    - Résultat obtenu ou verdict.
    - Fichiers ou actions concernés.
    - Vérifications exécutées et preuves observables.
    - Blocages ou limites restantes.
    

    sha256:3a9ad69a3a653d46822355a9d2593dd624c0efaac410197bae73b269ee9dba26

    Diagnostiquer un problème

    Trouve et corrige le défaut de Liste d’options

    # Déboguer Liste d’options dans ton agent
    
    ## Symptôme observé
    [DÉCRIS ICI LE SYMPTÔME]
    
    ## Contrôles observables
    - Reproduis le problème avec le plus petit parcours pertinent.
    - Compare le comportement aux états et transitions documentés de Liste d’options.
    - Vérifie le clavier, le focus, le nom accessible et les annonces.
    
    ## Causes possibles
    - La primitive employée ne correspond pas au comportement attendu.
    - Un état, une transition ou un retour de focus manque.
    - Le composant voisin capture un événement ou masque un signal accessible.
    
    ## Corrections bornées
    - Corrige la cause reproduite sans recréer les composants voisins.
    - Conserve le contrat public et ajoute un test ciblé de non-régression.
    - N’installe aucune dépendance et ne modifie aucun état distant sans autorisation.
    
    ## Vérification finale
    - Les options appartiennent à une liste nommée, autonome ou contextuelle
    - La relation entre focus et sélection est déclarée, notamment si la sélection suit le focus
    - Les flèches, Début et Fin sont cohérents
    - Le mode de sélection est explicite
    
    ## Garde-fous
    - Montre d’abord les changements envisagés avant toute action externe.
    - Ne publie, n’envoie, ne supprime, ne paie et ne modifie aucun état distant sans autorisation explicite.
    - Préserve les changements sans rapport et arrête-toi si le périmètre devient ambigu.
    
    ## Format de sortie
    - Résultat obtenu ou verdict.
    - Fichiers ou actions concernés.
    - Vérifications exécutées et preuves observables.
    - Blocages ou limites restantes.
    
    • Web platform
    • Prérequis · Accès au dépôt, au design system et aux tests
    Pourquoi ça marche
    • Le symptôme explicite évite de partir d’une correction supposée.
    • Les contrôles séparent comportement, accessibilité et interférences voisines.
    • La correction reste bornée et doit produire une preuve de non-régression.

    À essayer ensuite

    Verrouille la correction de Liste d’options

    # Empêcher la régression de Liste d’options
    
    ## Objectif
    Transforme la cause reproduite en test de non-régression ciblé et compare Liste d’options aux concepts voisins avant d’élargir la correction.
    
    ## Contrôles
    - Prouve que le test échoue avant la correction.
    - Prouve qu’il passe après la correction bornée.
    - Vérifie qu’aucun composant voisin n’a changé de comportement.
    
    ## Garde-fous
    - Montre d’abord les changements envisagés avant toute action externe.
    - Ne publie, n’envoie, ne supprime, ne paie et ne modifie aucun état distant sans autorisation explicite.
    - Préserve les changements sans rapport et arrête-toi si le périmètre devient ambigu.
    
    ## Format de sortie
    - Résultat obtenu ou verdict.
    - Fichiers ou actions concernés.
    - Vérifications exécutées et preuves observables.
    - Blocages ou limites restantes.
    

    sha256:030811abc17768b941b0617f10cff894ae1b67b9c1e3a84183f2d3b746a68827

    Fiche complète, enregistrement et provenance

    Instruction pré-écrite par SkillCodex — ta demande n’est ni envoyée ni utilisée pour adapter ce texte ; aucun contenu n’est généré et copier n’exécute rien.

    Digest du Pack: sha256:d6e5c7329cf64ab1600c88dee71f419a83061d83be2e523a9c0d312ada9bd0bd

    Dans le code

    TechnologiePrimitiveVersionLimite
    Web platform

    select[size]

    NatifLe spécimen utilise un select natif affichant plusieurs lignes. Une listbox ARIA personnalisée exige une navigation et une sélection complètes.

    Détails techniques

    Comportements

    • Parcourir les options

      Les flèches parcourent les options selon le modèle déclaré du contrôle ; les états de focus et de sélection sont exposés de façon cohérente, y compris lorsque la sélection suit le focus.

    • Déclarer le mode de sélection

      Le contrôle expose si une ou plusieurs valeurs peuvent être sélectionnées et met à jour chaque état sélectionné de façon cohérente.

    États

    • Période par défaut sélectionnée

      Période par défaut sélectionnée

    • 30 derniers jours sélectionnés

      30 derniers jours sélectionnés

    Transitions d’état

    • Période par défaut sélectionnée → 30 derniers jours sélectionnés

      Dans cet exemple natif à sélection simple, la navigation par flèches atteint 30 derniers jours et met immédiatement à jour la valeur sélectionnée.

    • 30 derniers jours sélectionnés → Période par défaut sélectionnée

      Dans cet exemple natif à sélection simple, la navigation revient à la période par défaut et met immédiatement à jour la valeur sélectionnée.

    Scénarios de test

    Contexte
    Un générateur de rapports affiche quatre périodes visibles et permet d'en choisir exactement une.
    Mission
    Focaliser la liste, atteindre 30 derniers jours avec les flèches, sélectionner et vérifier que l'état reste visible.
    État principal
    Les quatre périodes restent visibles ; la ligne sélectionnée est mise en évidence et reprise dans le statut. Cet exemple natif ne sépare pas un état actif d'un état validé.
    Cas limite
    Une période personnalisée désactivée est annoncée, ignorée selon le modèle clavier et jamais confondue avec la valeur choisie.

    Signaux visuels

    • Options regroupées dans une surface composite
    • Une ou plusieurs options sélectionnées gardent un état persistant
    • La surface peut être autonome ou apparaître comme surface associée

    Signaux comportementaux

    • Les flèches circulent dans un contrôle composite
    • La sélection peut suivre le focus ou demander validation
    • Le mode simple ou multiple est déclaré

    Accessibilité

    Rôle
    listbox > option
    Nom accessible
    Le contrôle principal ou la région nommée pour Liste d'options possède un nom accessible stable issu d’un texte visible ou d’un libellé programmatique explicite ; le placeholder et l’infobulle ne servent pas de nom.
    Focus clavier
    Le select natif affichant plusieurs lignes forme un seul arrêt de tabulation. Dans cet exemple à sélection simple, la sélection suit le focus clavier : états actif et sélectionné évoluent ensemble ; une listbox personnalisée doit déclarer son propre modèle.
    Fermeture
    Dans cet exemple autonome, quitter avec Tab conserve la valeur sélectionnée ; lorsqu'une listbox est contextuelle, sa fermeture est coordonnée par le contrôle propriétaire.
    Défilement
    Une longue collection d'options défile sans déplacer la page située derrière, et l'option active ou sélectionnée reste visible.
    Annonce
    Le nom de la liste, ses quatre options, la sélection, l'état désactivé et le mode simple de cet exemple sont exposés par la sémantique native.
    Clavier
    • Tab entre une fois dans le contrôle composite
    • Dans cet exemple natif à sélection simple, les flèches mettent la sélection à jour avec le focus
    • Cet exemple n'a pas de commande de validation séparée
    • Les touches Début et Fin prises en charge par la plateforme atteignent les limites

    Implémentations

    Ouvrir la matrice HTML, ARIA, Radix et shadcn
    • select[size]

      implementationKind
      native
      nativeElement
      select[size]
      ariaPattern
      listbox
      radixPrimitive
      Non applicable
      shadcnRecipe
      Non applicable
      runtimeDependency
      Non applicable
      packageName
      Non applicable
      exportName
      Non applicable
      exactVersion
      Non applicable
      status
      verified
      sourceId
      source-ui-html-select
      deprecationStatus
      active
      replacement
      Non applicable
      validFrom
      Non applicable
      validUntil
      Non applicable

      Limite d’équivalence : Le spécimen utilise un select natif affichant plusieurs lignes. Une listbox ARIA personnalisée exige une navigation et une sélection complètes.

      Vérifier la source du binding

    Sources

    • WAI-ARIA APG: Listbox Pattern
      sourceId
      source-ui-aria-listbox
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/ARIA/apg/patterns/listbox/
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-09T07:07:36Z
      consultedAt
      2026-07-19
      license
      Non indiquée
      contentDigest
      sha256:7d0369bdd2fb3122cb1164a16ea1cb0b36960aaf5cc4e24e9c2bdedd888f050e
      status
      verified

      Affirmation couverte : Liste d'options : guide APG informatif pour le modèle listbox : rôles, états, relations et interactions au clavier.

    • WHATWG HTML: The select element
      sourceId
      source-ui-html-select
      kind
      standard
      canonicalUrl
      https://html.spec.whatwg.org/multipage/form-elements.html#the-select-element
      publisher
      WHATWG
      sourceRevision
      http-last-modified:2026-07-19T13:52:46Z
      consultedAt
      2026-07-19
      license
      Non indiquée
      contentDigest
      sha256:418a8f9ce1e8690c6d458121120b0b3b7cd907aa92b2101b85f82f7e02d5ac2f
      status
      verified

      Affirmation couverte : Liste d'options : sémantique native normative, états, attributs et comportement du navigateur pour select.

    • WAI-ARIA 1.2: Roles Model
      sourceId
      source-ui-wai-aria-roles
      kind
      standard
      canonicalUrl
      https://www.w3.org/TR/wai-aria-1.2/#roles
      publisher
      W3C WAI
      sourceRevision
      W3C-REC-wai-aria-1.2-20230606
      consultedAt
      2026-07-19
      license
      Non indiquée
      contentDigest
      sha256:c0fea16fc747779569ab754d2d25bca3e2b7e8a673b8ef5362aeb9ebc73a4849
      status
      verified

      Affirmation couverte : Liste d'options : définitions normatives des rôles ARIA et contraintes du rôle accessible indiqué.

    • WCAG 2.2: Focus Appearance
      sourceId
      source-ui-wcag-understanding-focus-appearance
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-02T10:07:49Z
      consultedAt
      2026-07-19
      license
      Non indiquée
      contentDigest
      sha256:fdcf316a1f0e3cc758eda9618322d132862124ff0a3f3b1a3acbf20daf804ff0
      status
      verified

      Affirmation couverte : Liste d'options : guide WCAG informatif pour évaluer l'apparence visible du focus clavier.

    • WHATWG HTML: Forms
      sourceId
      source-ui-html-forms
      kind
      standard
      canonicalUrl
      https://html.spec.whatwg.org/multipage/forms.html
      publisher
      WHATWG
      sourceRevision
      http-last-modified:2026-07-19T13:52:46Z
      consultedAt
      2026-07-19
      license
      Non indiquée
      contentDigest
      sha256:730c20c8a823ab6b9a40c77d4731d6aab46895cd98c388fe12c966096d5bdd18
      status
      verified

      Affirmation couverte : Liste d'options : sémantique native normative, états, attributs et comportement du navigateur pour HTML form controls.