Skip to content

Commit ca3c4b2

Browse files
authored
Merge pull request #3775 from department-of-veterans-affairs/3567-Add-Combo-box-documentation
Added combo box guidance
2 parents 82d967a + 72f569e commit ca3c4b2

File tree

6 files changed

+107
-4
lines changed

6 files changed

+107
-4
lines changed

src/_components/form/combo-box.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
layout: component
3+
permalink: /components/form/combo-box
4+
has-parent: /components/form/
5+
title: Combo box
6+
intro-text: "A combo box helps users select an item from a large list of options."
7+
research-title: Form controls
8+
status: use-with-caution-candidate
9+
figma-link: https://www.figma.com/design/afurtw4iqQe6y4gXfNfkkk/VADS-Component-Library?node-id=19200-2377
10+
uswds-v3: default
11+
web-component: va-combo-box
12+
anchors:
13+
- anchor: Examples
14+
- anchor: Usage
15+
- anchor: Code usage
16+
- anchor: Accessibility considerations
17+
- anchor: Related
18+
- anchor: Component checklist
19+
---
20+
21+
## Examples
22+
23+
### Default
24+
25+
{% include storybook-preview.html story="uswds-va-combo-box--default" link_text="va-combo-box default" height="300px" %}
26+
27+
### With Default Value
28+
29+
{% include storybook-preview.html story="uswds-va-combo-box--with-default-value" link_text="va-combo-box with default value" height="300px" %}
30+
31+
### With Error
32+
33+
{% include storybook-preview.html story="uswds-va-combo-box--with-error" link_text="va-combo-box with error" height="300px" %}
34+
35+
### Required
36+
37+
{% include storybook-preview.html story="uswds-va-combo-box--required" link_text="va-combo-box required" height="300px" %}
38+
39+
### With Placeholder Text
40+
41+
{% include storybook-preview.html story="uswds-va-combo-box--with-placeholder-text" link_text="va-combo-box with placeholder text" height="300px" %}
42+
43+
### With Hint Text
44+
45+
{% include storybook-preview.html story="uswds-va-combo-box--with-hint-text" link_text="va-combo-box with hint text" height="300px" %}
46+
47+
### With Message Aria Described By
48+
49+
{% include storybook-preview.html story="uswds-va-combo-box--with-message-aria-described-by" link_text="uswds-va-combo-box with message aria described by" height="300px" %}
50+
51+
## Usage
52+
53+
<a class="vads-c-action-link--blue" href="https://designsystem.digital.gov/components/combo-box/">Refer to the U.S. Web Design System for usage guidance</a>
54+
55+
{% include content/select-options.md %}
56+
57+
### Errors
58+
59+
* Refer to the specific [error example](#with-error) above.
60+
61+
<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/components/form/#error-handling">
62+
View form error handling for additional guidance
63+
</a>
64+
65+
### Hint text
66+
67+
* Refer to the [hint text example](#with-hint-text) above.
68+
69+
<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/components/form/label#hint-text">
70+
View label hint text for additional guidance
71+
</a>
72+
73+
{% include component-docs.html component_name=page.web-component %}
74+
75+
## Accessibility considerations
76+
77+
<a class="vads-c-action-link--blue" href="https://designsystem.digital.gov/components/combo-box/#accessibility-guidance">Refer to the U.S. Web Design System for accessibility guidance</a>
78+
79+
## Related
80+
81+
* [Select]({{ site.baseurl }}/components/form/select)
82+
* [Radio button]({{ site.baseurl }}/components/form/radio-button)
83+
* [Search input]({{ site.baseurl }}/components/search-input)
84+
85+
{% include _component-checklist.html component_name=page.web-component %}

src/_components/form/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ status: use-deployed
88
sub-pages:
99
- sub-page: Autosave
1010
- sub-page: Checkbox
11+
- sub-page: Combo box
1112
- sub-page: Date input
1213
- sub-page: Memorable date
1314
- sub-page: File input

src/_components/form/radio-button.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,8 @@ anchors:
6363

6464
<a class="vads-c-action-link--blue" href="https://designsystem.digital.gov/components/radio-buttons/">Refer to the U.S. Web Design System for usage guidance</a>
6565

66+
{% include content/select-options.md %}
67+
6668
### Choosing between variations
6769

6870
* Use the [Hint text](#hint-text) variation to provide additional information that pertains to the question being asked or all of the options presented.

src/_components/form/select.md

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ anchors:
2727

2828
{% include storybook-preview.html story="uswds-va-select--required" link_text="va-select required" %}
2929

30-
### With hint text
30+
### Hint text
3131

3232
{% include storybook-preview.html story="uswds-va-select--with-hint-text" link_text="va-select with hint text" %}
3333

@@ -57,9 +57,7 @@ anchors:
5757

5858
### Additional guidance for VA
5959

60-
#### Additional reasons to consider something else
61-
62-
**More than 15 options.** If the list of options is very long, we do not yet have the combo box component in our system thus an alternative is to use functionality that allows users to type the same information into a text input that suggests possible options instead as seen in our [search input]({{ site.baseurl }}/components/search-input) component.
60+
{% include content/select-options.md %}
6361

6462
### Errors
6563

src/_components/search-input.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ web-component: va-search-input
5252

5353
* When free text input is allowed, do not use type-ahead in form fields where the user might assume they are limited to selecting a suggested term. Alternatively, provide a clear way for the user to add an entry if you do use type-ahead in a form field.
5454

55+
{% include content/select-options.md %}
56+
5557
### Placement
5658

5759
* The search input component should only appear in the global header, on search results pages, and in search-related tools such as Resources and Support and Find a VA Form.
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
### Choosing the right component for the task
2+
Consider how many options the user will have when choosing the right component. The number of options will determine what component is right for the task.
3+
4+
* **2 - 5: Radio Buttons.** Use [radio buttons]({{ site.baseurl }}/components/form/radio-button) when there are only a few options that can all be exposed at once.
5+
* **6 - 15: Select.** Use a [select]({{ site.baseurl }}/components/form/select) for a limited number of options.
6+
* **16 - 100: Combo Box.** For over 15 items, use a [combo box]({{ site.baseurl }}/components/form/combo-box) that combines a select with typeahead.
7+
* **101 - ∞: Search Input typeahead.** Over 100 items, use the [search input]({{ site.baseurl }}/components/search-input) component with typeahead.
8+
9+
### Some exceptions when choosing the right component
10+
Some exceptions can be considered when choosing the right component.
11+
12+
* **When the options are known and memorable.** Use the combo box when the user will know what to expect as options in the dropdown. Some examples of this would be a list of countries or states. See the [USWDS address pattern](https://designsystem.digital.gov/patterns/create-a-user-profile/address/#guidance-2) for an example.
13+
* **When the radio button labels are long or radio tiles contain descriptive text.** Using long labels within a dropdown might create an issue where the information needed to make a selection is lost. There's also descriptive text added within radio tiles that can't be used in a dropdown. In those use cases a radio button might be required instead of a dropdown opton.
14+
15+
These are some things to consider when choosing between different components. Contact the Design System team for help if you have other use cases that are considered exceptions.

0 commit comments

Comments
 (0)