1- import { useState } from ' react'
1+ import { useState , useEffect } from ' react'
22import { Meta , Story , Canvas , ArgsTable } from ' @storybook/addon-docs'
33import { Combobox , CreatableCombobox , ComboboxOption } from ' @strapi/design-system'
44
55<Meta title = " Design System/Components/Combobox" component = { Combobox } />
66
77# Combobox
88
9+ An input field designed to not only offer users the ability to type the value they want,
10+ but also display a panel of suggestions which filter & autocomplete as the user types for a
11+ more fluid experience. This shouldn't be confused with the [ ` Select ` ] ( /docs/design-system-components-select--basic )
12+ component!
13+
914[ View source] ( https://github.com/strapi/design-system/tree/main/packages/strapi-design-system/src/Combobox )
1015
11- ## Imports
16+ ## Usage
1217
1318``` js
14- import { Combobox } from ' @strapi/design-system'
19+ import { Combobox , ComboboxOption , CreatableCombobox } from ' @strapi/design-system'
1520```
1621
17- ## Usage
18-
19- This ` Combobox ` can be found in forms. They give users to search and choose a value from given options.
20-
21- ### Base
22+ ### Basic Usage
2223
23- In addition ` Combobox ` can also include a placeholder and a description line.
24+ By default, the combobox uses both inline and list autocomplete, that is where as the user types suggestions
25+ (based on the order of the options) are shown in the input field whilst the list gradually gets filtered.
2426
2527<Canvas >
26- <Story name = " base "
28+ <Story name = " basic "
2729 { () => {
2830 const = useState (' '
2931 return (
30- <Combobox label = " Food" value = { value } onChange = { setValue } >
31- <ComboboxOption value = " hamburger" ComboboxOption
32- <ComboboxOption value = " bagel" ComboboxOption
33- <ComboboxOption value = " tartuffo" ComboboxOption
34- <ComboboxOption value = " carbonara" ComboboxOption
32+ <Combobox
33+ placeholder = " My favourite fruit is..."
34+ label = " Fruits"
35+ value = { value }
36+ onChange = { setValue }
37+ onClear = { () => setValue (' ' }
38+ >
39+ <ComboboxOption value = " apple" ComboboxOption
40+ <ComboboxOption value = " avocado" ComboboxOption
41+ <ComboboxOption value = " banana" ComboboxOption
42+ <ComboboxOption value = " kiwi" ComboboxOption
43+ <ComboboxOption value = " mango" ComboboxOption
44+ <ComboboxOption value = " orange" ComboboxOption
45+ <ComboboxOption value = " strawberry" ComboboxOption
3546 </Combobox
3647 );
3748 }}
3849 </Story >
3950</Canvas >
4051
41- ### Disabled
52+ ### Async data
4253
43- Depending on the permissions a user have or the status of an action, a ` Combobox ` can be unreachable or unavailable yet.
54+ In some situations it might not be optimal to load all the data at once. In this case,
55+ you can use the ` loading ` prop to load more data when the user scrolls to the bottom of the list.
4456
45- <Canvas >
46- <Story name = " disabled"
47- { () => {
48- const = useState (' '
49- return (
50- <Combobox label = " Food" disabled value = { value } onChange = { setValue } >
51- <ComboboxOption value = " hamburger" ComboboxOption
52- <ComboboxOption value = " bagel" ComboboxOption
53- <ComboboxOption value = " tartuffo" ComboboxOption
54- <ComboboxOption value = " carbonara" ComboboxOption
55- </Combobox
56- );
57- }}
58- </Story >
59- </Canvas >
60-
61- ### Without label
62-
63- ` Combobox ` can be used without a label.
57+ NOTE! You also need to supply an ` onLoadMore ` callback as well as defining if ` hasMoreItems `
58+ is true to show the spinner. In future iterations, we plan to omit the ` hasMoreItems ` prop.
6459
6560<Canvas >
66- <Story name = " withoutLabel "
61+ <Story name = " loading "
6762 { () => {
68- const = useState (' '
63+ const = useState (false );
64+ const = () => setIsLoading (true );
65+ useEffect (() => {
66+ if (isLoading ) {
67+ const = setTimeout (() => {
68+ setIsLoading (false );
69+ }, 2000 );
70+ return () => clearTimeout (timeout );
71+ }
72+ }, [isLoading ]);
6973 return (
70- <Combobox aria-label = " Food" value = { value } onChange = { setValue } >
71- <ComboboxOption value = " hamburger" ComboboxOption
72- <ComboboxOption value = " bagel" ComboboxOption
73- <ComboboxOption value = " tartuffo" ComboboxOption
74- <ComboboxOption value = " carbonara" ComboboxOption
74+ <Combobox
75+ label = " Async Fruits"
76+ placeholder = " My favourite fruit is..."
77+ loading = { isLoading }
78+ onLoadMore = { handleLoadMore }
79+ hasMoreItems
80+ >
81+ <ComboboxOption value = " apple" ComboboxOption
82+ <ComboboxOption value = " avocado" ComboboxOption
83+ <ComboboxOption value = " banana" ComboboxOption
84+ <ComboboxOption value = " kiwi" ComboboxOption
85+ <ComboboxOption value = " mango" ComboboxOption
86+ <ComboboxOption value = " orange" ComboboxOption
87+ <ComboboxOption value = " strawberry" ComboboxOption
7588 </Combobox
7689 );
7790 }}
7891 </Story >
7992</Canvas >
8093
81- ### Error
94+ ### Creating new options
8295
83- ` Combobox ` can display an error. The error message is customizable and replaces the description line below the input.
84-
85- <Canvas >
86- <Story name = " error"
87- { () => {
88- const = useState (' '
89- return (
90- <Combobox label = " Food" value = { value } error = " An error occured" onChange = { setValue } >
91- <ComboboxOption value = " hamburger" ComboboxOption
92- <ComboboxOption value = " bagel" ComboboxOption
93- <ComboboxOption value = " tartuffo" ComboboxOption
94- <ComboboxOption value = " carbonara" ComboboxOption
95- </Combobox
96- );
97- }}
98- </Story >
99- </Canvas >
100-
101- ### Required
102-
103- ` Combobox ` can be required. The required state will appear with a red asterisk beside the label.
104-
105- <Canvas >
106- <Story name = " required"
107- { () => {
108- const = useState (' '
109- return (
110- <Combobox label = " Food" value = { value } required onChange = { setValue } >
111- <ComboboxOption value = " hamburger" ComboboxOption
112- <ComboboxOption value = " bagel" ComboboxOption
113- <ComboboxOption value = " tartuffo" ComboboxOption
114- <ComboboxOption value = " carbonara" ComboboxOption
115- </Combobox
116- );
117- }}
118- </Story >
119- </Canvas >
120-
121- ### Initial data
122-
123- This is the doc of the ` Combobox ` component
124-
125- <Canvas >
126- <Story name = " initial-data"
127- { () => {
128- const = useState (' tartuffo'
129- return (
130- <Combobox label = " Food" value = { value } onChange = { setValue } >
131- <ComboboxOption value = " hamburger" ComboboxOption
132- <ComboboxOption value = " bagel" ComboboxOption
133- <ComboboxOption value = " tartuffo" ComboboxOption
134- <ComboboxOption value = " carbonara" ComboboxOption
135- </Combobox
136- );
137- }}
138- </Story >
139- </Canvas >
140-
141- ### Creatable
142-
143- The creatable mode of ` Combobox ` allows the creation of a new options.
96+ If you want to allow users to create new options, you can use the ` CreatableCombobox ` component. This is
97+ just a wrapper around the ` Combobox ` component that pre-flags the ` creatable ` prop as ` true ` . You should
98+ still pass an ` onCreateOption ` callback to handle the creation of the new option.
14499
145100<Canvas >
146101 <Story name = " creatable"
147102 { () => {
148103 const = useState (' '
149104 const = useState ([
150105 {
151- name: ' Hamburger'
152- value: ' hamburger'
153- },
154- {
155- name: ' Hambu'
156- value: ' hambu'
157- },
158- {
159- name: ' Ham'
160- value: ' ham'
161- },
162- {
163- name: ' Sandwich'
164- value: ' sandwich'
165- },
166- {
167- name: ' Peperroni'
168- value: ' peperroni'
106+ name: ' Apple'
107+ value: ' apple'
169108 },
170109 {
171- name: ' Asparagus '
172- value: ' asparagus '
110+ name: ' Avocado '
111+ value: ' avocado '
173112 },
174113 {
175- name: ' Lettuce '
176- value: ' lettuce '
114+ name: ' Banana '
115+ value: ' banana '
177116 },
178117 {
179- name: ' Tomato '
180- value: ' tomato '
118+ name: ' Kiwi '
119+ value: ' kiwi '
181120 },
182121 {
183- name: ' Bagel '
184- value: ' bagel '
122+ name: ' Mango '
123+ value: ' mango '
185124 },
186125 {
187- name: ' Tartuffo '
188- value: ' tartuffo '
126+ name: ' Orange '
127+ value: ' orange '
189128 },
190129 {
191- name: ' Carbonara '
192- value: ' carbonara '
130+ name: ' Strawberry '
131+ value: ' strawberry '
193132 },
194133 ]);
195134 const = (value ) => {
196135 setOptions ((opt ) => [... opt , { name: value , value }]);
197136 setValue (value );
198137 };
199138 return (
200- <CreatableCombobox label = " Food" value = { value } onChange = { setValue } onCreateOption = { onCreateOption } >
139+ <CreatableCombobox
140+ label = " Fruits"
141+ placeholder = " My favourite fruit is..."
142+ value = { value }
143+ onChange = { setValue }
144+ onCreateOption = { onCreateOption }
145+ >
201146 { options .map (({ name , value }) => (
202147 <ComboboxOption key = { value } value = { value } >
203148 { name }
@@ -211,4 +156,14 @@ The creatable mode of `Combobox` allows the creation of a new options.
211156
212157## Props
213158
159+ ### Combobox
160+
214161<ArgsTable of = { Combobox } />
162+
163+ ### ComboboxOption
164+
165+ <ArgsTable of = { ComboboxOption } />
166+
167+ ### CreatableCombobox
168+
169+ <ArgsTable of = { CreatableCombobox } />
0 commit comments