Practical guide
6 min read
Updated
Let people choose several items
Choose checkboxes, a multiselect list or removable tokens, then verify keyboard selection and recovery.
Direct answer
Start with visible checkboxes for a short set. Use a multiple-selection list for a fixed collection, or a carefully tested search-and-token interaction for a large vocabulary. Keep chosen values visible, allow removal, and verify the submitted set.
01
1. Choose the control from the task
For a few visible, independent choices, start with labeled native checkboxes grouped under a shared question. For a longer fixed set, consider a native select with multiple enabled or an accessible multiselect listbox. Test the target browser and device: native multiple selection gestures are not identical everywhere.
If people search a large vocabulary and keep several chosen items as removable tokens, treat this as a composed interaction with its own selection and removal contract. A component called “combobox” does not by itself establish accessible multiple selection. Decide whether free text creates new values or only finds existing ones; do not silently accept misspellings as new records.
02
2. Distinguish focus from selection
Focus identifies where the next keyboard action applies; selection records the values that will be used. In the recommended APG multiselect listbox model, arrow keys move focus and Space toggles the focused option without requiring a modifier. Moving past an option must not silently erase earlier choices. Expose the list’s multiple-selection capability and each option’s selected state consistently.
A listbox option is not a container for independently operable links or buttons. If rows need separate actions, choose a different interaction rather than nesting those controls inside options. A checkbox group has its own keyboard behavior: Tab reaches individual controls and Space changes the focused checkbox. Do not transplant the listbox arrow model onto unrelated native inputs.
03
3. Make the selected set explicit
Original scenario: a reading list can carry the topics Design, Testing and Writing. Ask “Which topics belong to this list?” and permit zero to three choices. Begin with no choices, select Design and Testing, then remove Design. The saved value must contain only Testing; the visual focus location is irrelevant to that payload.
Use stable identifiers for values and translated labels for display. Show the chosen items and a count when the choices can disappear behind filtering. State whether “Select all” concerns visible results or the entire collection. This distinction becomes essential when a query hides choices already made. Keep the set intact while changing the filter.
04
4. Allow removal and recovery
Provide an explicit way to remove a choice and clear the set. A removable token needs an accessible action name identifying its value. After removal, keep focus in a useful predictable place such as the next removal action or the input. Clearing a filter and clearing selected values are different actions; name them accordingly.
If applying the choices fails, preserve the draft set and explain how to retry. For an applied destructive operation, selection alone is not authorization to execute it. In this reading-list example, changing labels is reversible; offer a route to edit them again. A disabled option needs an explanation when its unavailability would otherwise be confusing.
05
5. Verify the complete journey
Run the example with keyboard only, then with the target screen reader and touch device. Check the question, labels, focus visibility, selected states, removal names and final submitted values. Select nonadjacent options, filter, return, clear, and submit an empty set if allowed. Record any untested platform rather than claiming universal support.
For asynchronous options, reproduce a slow first query followed by a faster second one. Only the current result set should appear; selected values must retain their identity when temporarily absent. This is a test case, not a diagnosis of a particular race condition. Virtualized lists and very large remote vocabularies require additional implementation-specific accessibility checks.
- Select Design and Testing, then remove Design: only Testing remains.
- Filter to Writing and clear the query: Testing remains selected.
- Clear selected values and apply: the submitted set is empty if allowed.
Keep this
Verify before delivery
- 01The control matches the size and independence of the choices.
- 02Focus movement does not unexpectedly erase selections.
- 03Individual removal, clear and retry preserve the stated contract.
- 04Keyboard, assistive technology and submitted values were checked.
- 05Filtering retains selected values and defines the scope of Select all.
- 06Slow responses do not replace newer results or lose chosen identifiers.
Primary sources
Technical claims in this guide connect to first-party specifications and documentation.
- Listbox Pattern (opens in a new tab)W3C · Selection models, focus and option semantics; does not certify a component.
- Checkbox Pattern (opens in a new tab)W3C · Labeled groups and checked states.
- The select element (opens in a new tab)MDN Web Docs · Native multiple selection and platform-dependent interaction.
Continue
Related guides and tools
Understand → Recognize → Choose → Compare
Pack for your agent
Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.
Implement correctly
Apply “Let people choose several items” step by step
# Apply the “Let people choose several items” guide in your agent ## Objective Start with visible checkboxes for a short set. Use a multiple-selection list for a fixed collection, or a carefully tested search-and-token interaction for a large vocabulary. Keep chosen values visible, allow removal, and verify the submitted set. ## Prerequisites - Inspect the repository, documentation, and existing conventions. - Confirm the need matches the guide scope: Choose checkboxes, a multiselect list or removable tokens, then verify keyboard selection and recovery. - Preserve the correct decisions already in place. ## Guide steps - 1. 1. Choose the control from the task — For a few visible, independent choices, start with labeled native checkboxes grouped under a shared question. For a longer fixed set, consider a native select with multiple enabled or an accessible multiselect listbox. Test the target browser and device: native multiple selection gestures are not identical everywhere. - 2. 2. Distinguish focus from selection — Focus identifies where the next keyboard action applies; selection records the values that will be used. In the recommended APG multiselect listbox model, arrow keys move focus and Space toggles the focused option without requiring a modifier. Moving past an option must not silently erase earlier choices. Expose the list’s multiple-selection capability and each option’s selected state consistently. - 3. 3. Make the selected set explicit — Original scenario: a reading list can carry the topics Design, Testing and Writing. Ask “Which topics belong to this list?” and permit zero to three choices. Begin with no choices, select Design and Testing, then remove Design. The saved value must contain only Testing; the visual focus location is irrelevant to that payload. - 4. 4. Allow removal and recovery — Provide an explicit way to remove a choice and clear the set. A removable token needs an accessible action name identifying its value. After removal, keep focus in a useful predictable place such as the next removal action or the input. Clearing a filter and clearing selected values are different actions; name them accordingly. - 5. 5. Verify the complete journey — Run the example with keyboard only, then with the target screen reader and touch device. Check the question, labels, focus visibility, selected states, removal names and final submitted values. Select nonadjacent options, filter, return, clear, and submit an empty set if allowed. Record any untested platform rather than claiming universal support. ## Acceptance criteria — Verify before delivery - The control matches the size and independence of the choices. - Focus movement does not unexpectedly erase selections. - Individual removal, clear and retry preserve the stated contract. - Keyboard, assistive technology and submitted values were checked. - Filtering retains selected values and defines the scope of Select all. - Slow responses do not replace newer results or lose chosen identifiers. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The steps come from a published, sourced guide, not improvisation.
- The checklist turns advice into verifiable criteria.
- The declared scope keeps the guide within its evidence.
Try next
Anchor the guide in the project
# Anchor the guide in the project ## Objective Turn the applied steps into durable repository conventions. ## Checks - Link each decision made to the guide step that justifies it. - Add the checklist to the relevant reviews. - Record out-of-scope cases for the neighboring guides. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:73e9ca3746aa9bdac598550254a4fd569753ed734f87ef1e79da6ab5b02dab13
Diagnose a problem
Diagnose a “Let people choose several items” guide gap
# Diagnose a failed application of the “Let people choose several items” guide ## Observed symptom [DESCRIBE THE SYMPTOM HERE] ## Observable checks - Replay the steps in order and note the first one that diverges: - 1. 1. Choose the control from the task — For a few visible, independent choices, start with labeled native checkboxes grouped under a shared question. For a longer fixed set, consider a native select with multiple enabled or an accessible multiselect listbox. Test the target browser and device: native multiple selection gestures are not identical everywhere. - 2. 2. Distinguish focus from selection — Focus identifies where the next keyboard action applies; selection records the values that will be used. In the recommended APG multiselect listbox model, arrow keys move focus and Space toggles the focused option without requiring a modifier. Moving past an option must not silently erase earlier choices. Expose the list’s multiple-selection capability and each option’s selected state consistently. - 3. 3. Make the selected set explicit — Original scenario: a reading list can carry the topics Design, Testing and Writing. Ask “Which topics belong to this list?” and permit zero to three choices. Begin with no choices, select Design and Testing, then remove Design. The saved value must contain only Testing; the visual focus location is irrelevant to that payload. - 4. 4. Allow removal and recovery — Provide an explicit way to remove a choice and clear the set. A removable token needs an accessible action name identifying its value. After removal, keep focus in a useful predictable place such as the next removal action or the input. Clearing a filter and clearing selected values are different actions; name them accordingly. - 5. 5. Verify the complete journey — Run the example with keyboard only, then with the target screen reader and touch device. Check the question, labels, focus visibility, selected states, removal names and final submitted values. Select nonadjacent options, filter, return, clear, and submit an empty set if allowed. Record any untested platform rather than claiming universal support. ## Possible causes - A step was skipped or executed out of order. - The actual need falls outside the guide scope. - A checklist criterion was never verified. ## Bounded fixes - Redo only the diverging step and what depends on it. - Document the gap if the guide scope does not cover the need. ## Final verification — Verify before delivery - The control matches the size and independence of the choices. - Focus movement does not unexpectedly erase selections. - Individual removal, clear and retry preserve the stated contract. - Keyboard, assistive technology and submitted values were checked. - Filtering retains selected values and defines the scope of Select all. - Slow responses do not replace newer results or lose chosen identifiers. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
- Requires · The real project context: repository, documentation, and existing constraints
Why it works
- The diagnosis replays ordered steps instead of searching at random.
- Fixes stay bounded to the first real divergence.
- The checklist serves as a reproducible final verification.
Try next
Prevent the next drift
# Prevent the next drift ## Objective Turn the first diverging step into an explicit project check. ## Checks - Add a focused check on the step that diverged. - Verify the checklist on a second real case. - Document the scope limit you hit. ## Guardrails - Show the proposed changes before any external action. - Do not publish, send, delete, pay for, or change remote state without explicit authorization. - Preserve unrelated changes and stop if the scope becomes ambiguous. ## Output format - Outcome or verdict. - Files or actions involved. - Checks run and observable evidence. - Remaining blockers or limitations.
sha256:0881aa06f4d1d69bb1cc2ac66ae95dcfe760c2efb39a8fc4b9b6eedb36525e12
Pack digest: sha256:dbe828e10b82d400cc50bd7cab3df764610170004a8fc808ca22465e47bc4639