@wix/design-system

## Feature Examples ### Size - description: Adjust the component size using the size prop.<li><code>large</code> emphasize fields in onboarding flows.</li><li><code>medium</code> is the default size used in most cases.</li><li><code>small</code> should be used in dense layouts.</li> - example: ```jsx () => { const options = [ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, ]; return ( <StorybookComponents.Stack flexDirection="column"> <Dropdown size="large" placeholder="Large" options={options} /> <Dropdown size="medium" placeholder="Medium" options={options} /> <Dropdown size="small" placeholder="Small" options={options} /> </StorybookComponents.Stack> ); }; ``` ### Border - description: Style the component using the border prop which supports four styles:<li>For forms, use <code>standard</code>.</li><li>When the component is used to filter, use <code>round</code>.</li><li>For titles that can be edited on click, use <code>bottomLine</code>.</li><li>In the Content Manager’s spreadsheet, use <code>none</code>.</li> - example: ```jsx () => { const options = [ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, ]; return ( <StorybookComponents.Stack flexDirection="column"> <Dropdown border="standard" placeholder="Standard" options={options} /> <Dropdown border="round" placeholder="Round" options={options} /> <Dropdown border="bottomLine" placeholder="Bottom Line" options={options} /> <Dropdown border="none" placeholder="None" options={options} /> </StorybookComponents.Stack> ); }; ``` ### Status - description: Use the <code>status</code> prop to control component status. <li><code>error</code> highlights an invalid selection.</li><li><code>warning</code> highlights a value that can’t be validated or impacts a user’s business.</li><li><code>loading</code> shows that the value is loading.</li>Hide the status suffix and indicate the state with a border color by setting <code>hideStatusSuffix</code>to true. - example: ```jsx () => { const options = [ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, ]; return ( <StorybookComponents.Stack flexDirection="column"> <Dropdown status="error" placeholder="Error" options={options} /> <Dropdown status="warning" placeholder="Warning" options={options} /> <Dropdown status="loading" placeholder="Loading" options={options} /> </StorybookComponents.Stack> ); }; ``` ### Status message - description: Add text that explains the status or what action the user should take with the <code>statusMessage</code> prop.Showing the status message inline, directly below the dropdown is preferred in all default cases.<li>To add an accessible inline message, wrap the component in a <code><FormField/></code> and add the <code>statusMessage</code>.</li><li>To add a status message in a tooltip that requires users to hover on the icon, use the <code>statusMessage</code> prop. Control tooltip placement with <code>tooltipPlacement</code> prop.</li>View more inline status message examples in <code><FormField/></code>. - example: ```jsx () => { const options = [ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, ]; return ( <StorybookComponents.Stack flexDirection="column"> <StorybookComponents.Stack flexDirection="column" gap="12px"> <Text secondary>For all default cases:</Text> <FormField status="error" statusMessage="This is an error message."> <Dropdown placeholder="See message below" tooltipPlacement="top-end" options={options} /> </FormField> </StorybookComponents.Stack> <StorybookComponents.Stack flexDirection="column" gap="12px"> <Text secondary>For narrow layouts only:</Text> <Dropdown placeholder="Hover on status icon" status="error" statusMessage="This is an error message." tooltipPlacement="top-end" options={options} /> </StorybookComponents.Stack> </StorybookComponents.Stack> ); }; ``` ### Disabled - description: Disable all input interactions with the <code>disabled</code> prop. Use it to highlight unavailable functions. - example: ```jsx () => { const options = [ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, ]; return <Dropdown disabled placeholder="Disabled" options={options} />; }; ``` ### Affix - description: Add additional information to <code>prefix</code> and <code>suffix</code> props (e.g. text, icons, buttons) to support the dropdown value. - example: ```jsx () => { const discountSuffixOptions = [ { id: 0, value: '5' }, { id: 1, value: '10' }, { id: 2, value: '15' }, ]; const discountAffixOptions = [ { id: 0, value: '10' }, { id: 1, value: '20' }, { id: 2, value: '30' }, ]; const languageOptions = [ { id: 0, value: 'English' }, { id: 1, value: 'French' }, { id: 2, value: 'Spanish' }, ]; const employeeOptions = [ { id: 0, value: 'Employee 1' }, { id: 1, value: 'Employee 2' }, { id: 2, value: 'Employee 3' }, ]; return ( <StorybookComponents.Stack flexDirection="column"> <Dropdown placeholder="Select discount size" suffix={<Input.Affix>%</Input.Affix>} options={discountSuffixOptions} /> <Dropdown placeholder="Select discount size" prefix={<Input.Affix>$</Input.Affix>} options={discountAffixOptions} /> <Dropdown placeholder="Select language" prefix={ <Input.IconAffix> <Icons.Languages /> </Input.IconAffix> } options={languageOptions} /> <Dropdown placeholder="Select employee" prefix={ <Input.Affix> <Avatar size="size18" /> </Input.Affix> } options={employeeOptions} /> </StorybookComponents.Stack> ); }; ``` ### Clear button - description: Enable a button that clears the dropdown value by using the <code>clearButton</code> prop. Show it when the field value is optional or has to be cleared often. - example: ```jsx () => { const [selectedOption, setSelectedOption] = React.useState(0); const options = [ { id: 0, value: 'Click clear button to remove selection' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, ]; return ( <Dropdown placeholder="Select" clearButton onClear={() => setSelectedOption(null)} onSelect={option => setSelectedOption(option.id)} selectedId={selectedOption} options={options} /> ); }; ``` ### Fixed header and footer - description: Add related actions to <code>fixedFooter</code> or <code>fixedHeader</code> areas. These headers and footers keep their position on scroll. - example: ```jsx () => { const options = [ { id: 1, value: 'Option 1' }, { id: 2, value: 'Option 2' }, { id: 3, value: 'Option 3' }, { id: 4, value: 'Option 4' }, { id: 5, value: 'Option 5' }, { id: 6, value: 'Option 6' }, { id: 7, value: 'Option 7' }, { id: 8, value: 'Option 8' }, { id: 9, value: 'Option 9' }, ]; return ( <Dropdown placeholder="Select" fixedHeader={<ListItemAction title="Fixed Header" />} fixedFooter={<ListItemAction title="Fixed Footer" />} options={options} /> ); }; ``` ### List item builders - description: Use three props to build custom layouts:<li><code>listItemSectionBuilder</code> groups items into sections by type. <a href="https://www.wix-style-react.com/storybook/?path=/story/components-form-dropdownlistitems--listitemsection"></a></li><li><code>listItemActionBuilder</code> adds a text button for related list actions. <a href="https://www.wix-style-react.com/storybook/?path=/story/components-form-dropdownlistitems--listitemaction"></a></li><li><code>listItemSelectBuilder</code> builds custom list designs. <a href="https://www.wix-style-react.com/storybook/?path=/story/components-form-dropdownlistitems--listitemselect"></a></li> - example: ```jsx () => { const listItemSectionOptions = [ listItemSectionBuilder({ id: 0, type: 'title', title: 'Group Title', }), { id: 1, value: 'Option 1' }, { id: 2, value: 'Option 2' }, { id: 3, value: 'Option 3' }, listItemSectionBuilder({ id: 3, type: 'divider', }), { id: 4, value: 'Option 4' }, ]; const listItemActionOptions = [ listItemActionBuilder({ id: 0, title: 'Action', }), { id: 1, value: 'Option 1' }, { id: 2, value: 'Option 2' }, { id: 3, value: 'Option 3' }, ]; const listItemSelectOptions = [ listItemSelectBuilder({ id: 0, prefix: <Avatar size="size30" />, title: 'Title', subtitle: 'Subtitle', suffix: 'Suffix', }), listItemSelectBuilder({ id: 1, prefix: <Avatar size="size30" />, title: 'Title', subtitle: 'Subtitle', suffix: 'Suffix', }), listItemSelectBuilder({ id: 2, prefix: <Avatar size="size30" />, title: 'Title', subtitle: 'Subtitle', suffix: 'Suffix', }), ]; return ( <StorybookComponents.Stack flexDirection="column"> <Dropdown placeholder="List Item Section" options={listItemSectionOptions} /> <Dropdown placeholder="List Item Action" options={listItemActionOptions} /> <Dropdown placeholder="List Item Select" options={listItemSelectOptions} /> </StorybookComponents.Stack> ); }; ``` ### List container dimensions - description: Control the container size for the list of options with these props:<li><code>maxHeightPixels</code> specifies the maximum height for longer lists.</li><li><code>dropdownWidth</code> matches content width or specifies pixels. Set width to ‘auto’ or ‘max-content.’</li><li><code>minWidthPixels</code> manually increases dropdown popover width.</li>By default, the dropdown matches the input field width. - example: ```jsx () => { const options = [ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, { id: 3, value: 'Option 4' }, { id: 4, value: 'Option 5' }, { id: 5, value: 'Option 6' }, { id: 6, value: 'Option 7' }, { id: 7, value: 'Option 8' }, ]; return ( <StorybookComponents.Stack> <Dropdown placeholder="Look at proportions" maxHeightPixels="200px" dropdownWidth="auto" minWidthPixels="400px" options={options} popoverProps={{ placement: 'bottom-start', }} /> </StorybookComponents.Stack> ); }; ``` ### Marked option - description: Once the dropdown is opened, use the <code>markedOption</code> to highlight the option. - example: ```jsx <Dropdown placeholder="Select an option" markedOption={1} options={[ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, ]} />; ``` ### Native support - description: Switch to <code>native</code> support for mobile usage. Avoid using it for desktop applications. - example: ```jsx () => { const options = [ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, { id: 3, value: 'Option 4' }, ]; return <Dropdown options={options} placeholder="Select as native" native />; }; ``` ### Text overflow - description: Control text overflow in the field with the <code>textOverflow</code>. Apply <code>clip</code> or <code>ellipsis</code>.Dropdown list options wrap by default. To apply ellipsis, select the items to be displayed with the <code>listItemSelectBuilder</code>. This isn't recommended. - example: ```jsx () => { const options = [ { id: 0, value: 'Option 1' }, { id: 1, value: 'Option 2' }, { id: 2, value: 'Option 3' }, { id: 3, value: 'Option 4' }, ]; const longOptions = [ { id: 0, value: 'This is a long value that make dropdown layout grow', }, { id: 1, value: 'This is a long value that make dropdown layout grow', }, { id: 2, value: 'This is a long value that make dropdown layout grow', }, ]; const longOptionsWithEllipsis = [ listItemSelectBuilder({ id: 0, title: 'This is a long value that make dropdown layout grow', ellipsis: true, }), listItemSelectBuilder({ id: 0, title: 'This is a long value that make dropdown layout grow', ellipsis: true, }), listItemSelectBuilder({ id: 0, title: 'This is a long value that make dropdown layout grow', ellipsis: true, }), ]; return ( <StorybookComponents.Stack flexDirection="column"> <StorybookComponents.Stack> <FormField label="Input value with ellipsis::"> <Dropdown options={options} placeholder="This field is showing ellipsis at the end of this line" textOverflow="ellipsis" /> </FormField> <FormField label="Input value clipped:"> <Dropdown options={options} placeholder="This field is clipping content at the end of this line" textOverflow="clip" /> </FormField> </StorybookComponents.Stack> <StorybookComponents.Stack> <FormField label="Options wrapped:"> <Dropdown options={longOptions} placeholder="Select wrapped option" /> </FormField> <FormField label="Options with ellipsis:"> <Dropdown options={longOptionsWithEllipsis} placeholder="Select clipped option" /> </FormField> </StorybookComponents.Stack> </StorybookComponents.Stack> ); }; ``` ## Developer Examples ### Lazy loading - description: Gradually load items with <code>infiniteScroll</code>, <code>loadMore</code> and <code>hasMore</code> props. - example: ```jsx () => { const [data, setData] = React.useState([]); const fetchMoreData = () => Promise.resolve( fetch(`/api/dropdown?limit=${5}&offset=${data.length}`), ).then(results => setData([...data, ...results])); React.useEffect(() => { fetchMoreData(); }, []); return ( <Dropdown placeholder="Select" options={data} infiniteScroll hasMore={true} loadMore={fetchMoreData} /> ); }; ``` ### Controlled - description: Component can be used in controlled mode by passing <code>selectedId</code> and <code>onSelect</code> props. - example: ```jsx () => { const [selectedId, setSelected] = React.useState(0); const options = [ listItemSelectBuilder({ id: 0, prefix: ( <Box> <Icons.Home /> </Box> ), title: 'Home address', label: 'Home address', }), listItemSelectBuilder({ id: 1, title: 'Work address', label: 'Work address', prefix: ( <Box> <Icons.Toolbox /> </Box> ), }), listItemSelectBuilder({ id: 2, title: 'Mailing address', label: 'Mailing address', prefix: ( <Box> <Icons.Email /> </Box> ), }), listItemSelectBuilder({ id: 3, title: 'Shipping address', label: 'Shipping address', prefix: ( <Box> <Icons.Archive /> </Box> ), }), listItemSelectBuilder({ id: 4, title: 'Other', label: 'Other', prefix: ( <Box> <Icons.Category /> </Box> ), }), ]; return ( <Dropdown placeholder="Select" selectedId={selectedId} valueParser={(option) => option.label} onSelect={(e) => setSelected(e.id)} options={options} /> ); }; ``` ## Common Use Case Examples ### Settings panel - description: Use dropdown to let users select a single item from a predefined list of options in a settings panel. - example: ```jsx () => { const [selectedOption, setSelectedOption] = React.useState(0); const [value, setValue] = React.useState(2); const options = [ { id: 0, value: 'Image' }, { id: 1, value: 'Video' }, { id: 2, value: 'Image and video' }, { id: 3, value: 'Document' }, { id: 4, value: 'Audio' }, ]; return ( <SidePanel maxHeight="576px" width="288px" skin="floating"> <SidePanel.Header title="Upload Settings" /> <SidePanel.Content noPadding> <SidePanel.Field> <FormField label="Supported file type"> <Dropdown placeholder="Select" size="small" options={options} onSelect={(option) => setSelectedOption(option.id)} selectedId={selectedOption} /> </FormField> </SidePanel.Field> <SidePanel.Field> <FieldSet gap="small" legend="Max number of files" columns="auto 60px" > <Slider onChange={setValue} min={0} max={10} value={value} displayMarks={false} /> <Input size="small" value={value} onChange={(e) => setValue(e.target.value)} /> </FieldSet> </SidePanel.Field> <SidePanel.Field> <FormField label="This field is"> <Checkbox size="small" checked> Required </Checkbox> </FormField> </SidePanel.Field> <SidePanel.Section title="Display settings"> <SidePanel.Field> <FormField label="Field title"> <Input size="small" placeholder="Enter field title"/> </FormField> </SidePanel.Field> <SidePanel.Field> <FormField label="Button text"> <Input size="small" value="Choose file"/> </FormField> </SidePanel.Field> </SidePanel.Section> </SidePanel.Content> </SidePanel> ); }; ``` ### Prefix icon - description: Use <code>listItemSelectBuilder</code> to create custom layouts for options in the dropdown. For example, use avatars, icons or images as prefix icons. - example: ```jsx () => { const options = [ listItemSelectBuilder({ id: 0, prefix: ( <Box> <Icons.Home /> </Box> ), title: 'Home address', label: 'Home address', }), listItemSelectBuilder({ id: 1, title: 'Work address', label: 'Work address', prefix: ( <Box> <Icons.Toolbox /> </Box> ), }), listItemSelectBuilder({ id: 2, title: 'Mailing address', label: 'Mailing address', prefix: ( <Box> <Icons.Email /> </Box> ), }), listItemSelectBuilder({ id: 3, title: 'Shipping address', label: 'Shipping address', prefix: ( <Box> <Icons.Archive /> </Box> ), }), listItemSelectBuilder({ id: 4, title: 'Other', label: 'Other', prefix: ( <Box> <Icons.Category /> </Box> ), }), ]; return ( <FormField label="Address type"> <Dropdown placeholder="Select" valueParser={option => option.label} options={options} /> </FormField> ); }; ``` ### Grouping - description: Use <code>listItemSectionBuilder</code> within the drop down to group options into categories. - example: ```jsx <Layout> <Cell span={12}> <FormField label="Product"> <Dropdown placeholder="Select" options={[ listItemSectionBuilder({ title: 'Most popular', }), { id: 1, value: 'Wix Stores' }, { id: 2, value: 'Wix Bookings' }, { id: 3, value: 'Wix Blog' }, listItemSectionBuilder({ title: 'Other', }), { id: 4, value: 'Wix Events' }, { id: 5, value: 'Wix Forum' }, { id: 6, value: 'Wix Restaurants' }, ]} /> </FormField> </Cell> <Cell span={12}> <FormField label="Role"> <Dropdown placeholder="Select" options={[ listItemSectionBuilder({ title: 'General', type: 'subheader', suffix: 'Edit', }), { id: 0, value: 'Website manager' }, { id: 1, value: 'Website designer' }, { id: 2, value: 'Back office manager' }, listItemSectionBuilder({ title: 'Content manager roles', type: 'subheader', suffix: 'Edit', }), { id: 3, value: 'Content collection manager' }, listItemSectionBuilder({ title: 'Blog roles', type: 'subheader', suffix: 'Edit', }), { id: 4, value: 'Blog editor' }, { id: 5, value: 'Blog writer' }, { id: 6, value: 'Guest writer' }, listItemSectionBuilder({ title: 'Booking roles', type: 'subheader', suffix: 'Edit', }), { id: 7, value: 'Bookings admin' }, { id: 8, value: 'Bookings staff member' }, ]} /> </FormField> </Cell> </Layout>; ```