Skip to content

Commit 2a57ad7

Browse files
eddimaneddiman
authored
docs(design-system-docs): add Autocomplete component documentation (#4945)
* docs(design-system-docs): add Autocomplete component documentation Closes #4443 * docs(design-system-docs): expand Autocomplete Figma section and tune iframe heights Refs #4443 * docs(design-system-docs): rewrite Autocomplete doc for designer audience Address PR review: - Guidelines paragraphs now answer when/why; iframes carry the how - Title Case headings to match other Inputs docs - Lighter Accessibility section, matching search.md style - Trim Do's/Don'ts to UX guidance; drop API-level rules and duplicate redirects - Remove duplicated guidance between sections
1 parent 236b55c commit 2a57ad7

2 files changed

Lines changed: 242 additions & 3 deletions

File tree

‎apps/design-system-docs/docs/components/inputs/autocomplete.md‎

Lines changed: 241 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,268 @@
22
title: Autocomplete
33
sidebar_position: 1
44
---
5+
56
# Autocomplete
67

8+
Autocomplete is a text input that filters a list of options as the user types and lets them pick one. It supports string and object option lists, custom option rendering, asynchronous search, and the ability to confirm a typed value that is not already in the list.
9+
10+
<iframe
11+
class="sb-iframe"
12+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--introduction"
13+
width="100%"
14+
height="350"
15+
frameborder="1"
16+
></iframe>
17+
18+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--introduction)
19+
720
## When to Use
821

22+
Use Autocomplete when users need to choose a single value from a list that is too long for radio buttons or a basic select, or when typing is faster than scrolling. It works well for known data sets such as countries, materials, or wells, and for server-side search where results stream in as the user types.
23+
24+
**Avoid Autocomplete for:**
925

26+
- Free-form text entry with no suggestions - use [TextField](./textfield) instead
27+
- Quick keyword search across a page or site - use [Search](./search) instead
28+
- A small, fixed set of mutually exclusive options - use Radio or a basic Select instead
29+
- Multi-value selection - the EDS 2.0 Autocomplete is single-select
30+
31+
## Structure
32+
33+
Autocomplete is a composite field that combines several pieces:
34+
35+
- **Label**: Identifies the field
36+
- **Description**: Optional context shown below the label
37+
- **Input**: The search field with a leading search icon
38+
- **Clear button**: A close icon that appears when the input has a value
39+
- **Listbox**: A popover that lists filtered options, anchored to the input
40+
- **Helper message**: Optional text below the input for validation feedback or hints
1041

1142
## Guidelines
1243

44+
### Controlled Selection
45+
46+
Use a controlled selection when the surrounding form, page, or another component needs to react to which option is currently chosen - for example to enable a Submit button or to drive a dependent field.
47+
48+
<iframe
49+
class="sb-iframe"
50+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--controlled"
51+
width="100%"
52+
height="350"
53+
frameborder="1"
54+
></iframe>
55+
56+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--controlled)
57+
58+
### Object Options
59+
60+
Use object options when each choice carries extra data beyond the label - an ID, a category, a relationship - so that information is available to the rest of the screen once a selection is made.
61+
62+
<iframe
63+
class="sb-iframe"
64+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--object-options"
65+
width="100%"
66+
height="350"
67+
frameborder="1"
68+
></iframe>
69+
70+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--object-options)
71+
72+
### Custom Option Rendering
73+
74+
Use a custom row when a single label is not enough to tell options apart - for example a name with a subtitle, an icon, or a status badge. Keep rows scannable and avoid stacking more than two lines of text.
75+
76+
<iframe
77+
class="sb-iframe"
78+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--custom-option-rendering"
79+
width="100%"
80+
height="350"
81+
frameborder="1"
82+
></iframe>
83+
84+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--custom-option-rendering)
85+
86+
### Disabled Options
87+
88+
Disable individual options when they exist in the data set but are not available right now - for example out of stock, restricted by role, or already chosen elsewhere. They stay visible so the user can see they exist, but cannot be selected.
89+
90+
<iframe
91+
class="sb-iframe"
92+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--disabled-options"
93+
width="100%"
94+
height="350"
95+
frameborder="1"
96+
></iframe>
97+
98+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--disabled-options)
99+
100+
### Allow Custom Value
101+
102+
Let users add a value that is not in the list when the data set is open-ended - tags, project codes, free-text categories. While the user types, an "Add" row appears at the top of the dropdown so they can confirm the new entry.
103+
104+
<iframe
105+
class="sb-iframe"
106+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--allow-custom-value"
107+
width="100%"
108+
height="350"
109+
frameborder="1"
110+
></iframe>
111+
112+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--allow-custom-value)
113+
114+
### Loading and Asynchronous Search
115+
116+
Use the loading state while results are being fetched from a server. For server-side search, turn off the built-in filtering and fetch results in response to input changes. Debounce the requests so the server is not called on every keystroke.
117+
118+
<iframe
119+
class="sb-iframe"
120+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--loading"
121+
width="100%"
122+
height="350"
123+
frameborder="1"
124+
></iframe>
125+
126+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--loading)
127+
128+
<iframe
129+
class="sb-iframe"
130+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--async"
131+
width="100%"
132+
height="350"
133+
frameborder="1"
134+
></iframe>
135+
136+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--async)
137+
138+
### Validation States
139+
140+
Show the error state to mark the field as invalid, and pair it with a helper message that tells the user what is wrong and how to fix it. Keep the message specific and short.
141+
142+
<iframe
143+
class="sb-iframe"
144+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--invalid"
145+
width="100%"
146+
height="350"
147+
frameborder="1"
148+
></iframe>
149+
150+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--invalid)
151+
152+
### Disabled and Read Only
153+
154+
Prefer read-only over disabled when the value should remain visible and copyable but cannot be edited. Use disabled only when the field is currently unavailable and the value is not meaningful to the user.
155+
156+
#### Disabled
157+
158+
<iframe
159+
class="sb-iframe"
160+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--disabled"
161+
width="100%"
162+
height="350"
163+
frameborder="1"
164+
></iframe>
165+
166+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--disabled)
167+
168+
#### Read Only
169+
170+
<iframe
171+
class="sb-iframe"
172+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--read-only"
173+
width="100%"
174+
height="105"
175+
frameborder="1"
176+
></iframe>
177+
178+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--read-only)
179+
180+
### Forms
181+
182+
Autocomplete works inside react-hook-form via Controller. Remember to reset the form value when the field is cleared so validation and submission stay in sync.
183+
184+
<iframe
185+
class="sb-iframe"
186+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--with-react-hook-form"
187+
width="100%"
188+
height="280"
189+
frameborder="1"
190+
></iframe>
191+
192+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--with-react-hook-form)
193+
194+
### Density
195+
196+
Autocomplete adapts to density modes. Spacious is the default; comfortable provides a more compact layout for dense UIs. The dropdown rows respond to density as well.
197+
198+
<iframe
199+
class="sb-iframe"
200+
src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-inputs-autocomplete--density-modes"
201+
width="100%"
202+
height="260"
203+
frameborder="1"
204+
></iframe>
205+
206+
[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-inputs-autocomplete--density-modes)
13207

14208
## Accessibility
15209

210+
Autocomplete implements the ARIA 1.2 combobox pattern. Labels, descriptions, and helper messages are wired up automatically, and the dropdown announces how many results are available as the user types.
211+
212+
**Keyboard support:**
213+
214+
- **Tab**: Move focus to and from the field
215+
- **Type**: Filter the list as you type
216+
- **Arrow Down / Arrow Up**: Open the listbox and move through options
217+
- **Enter**: Select the highlighted option, or confirm a typed custom value when custom values are allowed
218+
- **Escape**: Close the listbox without changing the selection
16219

17220
## Figma
18221

222+
The Autocomplete component lives in the **EDS Core Components** library as **Autocomplete [EDS]**.
223+
224+
### Variants
225+
226+
The component is defined by two variant axes:
19227

228+
- **State**: Default, Hover, Focus, Active, Active Add Option, Filled, Read-only, Disabled
229+
- **Validation**: Default, Error
20230

21-
### Do's and don'ts
231+
Every state combines with both validation values, except for Read-only and Disabled which are only published with Validation = Default - the error styling does not apply when the field cannot be edited.
232+
233+
### Properties
234+
235+
The component exposes the following Figma properties:
236+
237+
- **State** (variant): see list above
238+
- **Validation** (variant): Default or Error
239+
- **Title + Description** (boolean, default on): toggles the entire label block
240+
- **Helper Message** (boolean, default off): toggles the helper-message row beneath the field
241+
- **Helper Message Text** (text): content of the helper-message row
242+
- **Placeholder** (text): placeholder copy for the empty input
243+
- **Text area** (text): the filled-input value used when State = Filled
244+
245+
### Using Autocomplete in Figma
246+
247+
1. In Figma, open the **Assets Panel** and search for **Autocomplete [EDS]**
248+
2. Drag an instance into your frame
249+
3. In the **Design Panel**, set **State** and **Validation**, toggle **Title + Description** / **Helper Message**, and edit the **Placeholder**, **Text area**, and **Helper Message Text** values to match your content
250+
251+
## Do's and Don'ts
22252

23253
:::info **Do**
24254

25-
-
255+
- Provide a clear, visible label so users know what they are searching for
256+
- Keep option labels short and scannable so users can spot the right choice while typing
257+
- Use a helper message to explain validation errors and how to recover
258+
- Prefer read-only over disabled when the current value should remain visible and copyable
259+
26260
:::
27261

28262
:::danger **Don't**
29263

30-
-
264+
- Hide or omit the label - placeholder text is not a substitute
265+
- Use Autocomplete when the list is short enough for Radio or a basic Select - the extra typing is friction
266+
- Pre-fill the field with a placeholder that looks like a real value - users may submit it by mistake
267+
- Rely on the dropdown alone to communicate errors - always show a helper message
268+
31269
:::

‎apps/design-system-docs/sidebars.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ const sidebars: SidebarsConfig = {
5858
id: 'components/inputs/inputs',
5959
},
6060
items: [
61+
'components/inputs/autocomplete',
6162
'components/inputs/button',
6263
'components/inputs/search',
6364
'components/inputs/selection_controls',

0 commit comments

Comments
 (0)