Combobox

下拉列表框是一个可自动完成输入enables merchants to filter a list of options and select one or more values.

Use when merchants can select one option from a predefined or editable list.

import{Listbox,Combobox,Icon}from'@shopify/polaris';import{SearchMinor}from'@shopify/polaris-icons';import{使用State,使用Callback,使用Memo}from'react';functionComboboxExample(){constdeselectedOptions=使用Memo(()=>[{value:'rustic',label:'Rustic'},{value:'antique',label:'Antique'},{value:乙烯基的,label:'Vinyl'},{value:'vintage',label:'Vintage'},{value:'refurbished',label:'Refurbished'},],[],);const[selectedOption,setSelectedOption]=使用State<string|undefined>();const[inputValue,setInputValue]=使用State('');const[options,setOptions]=使用State(deselectedOptions);constupdateText=使用Callback((value:string)=>{setInputValue(value);if(value===''){setOptions(deselectedOptions);return;}constfilterRegex=newRegExp(value,'i');constresultOptions=deselectedOptions.filter((option)=>option.label.match(filterRegex),);setOptions(resultOptions);},[deselectedOptions],);constupdateSelection=使用Callback((selected:string)=>{constmatchedOption=options.find((option)=>{returnoption.value.match(selected);});setSelectedOption(selected);setInputValue((matchedOption&&matchedOption.label)||'');},[options],);constoptionsMarkup=options.length>0?options.map((option)=>{const{label,value}=option;return(<Listbox.Optionkey={`${value}`}value={value}selected={selectedOption===value}accessibilityLabel={label}>{label}</Listbox.Option>);}):null;return(<div style={{height:'225px'}}><Comboboxactivator={<Combobox.TextFieldprefix={<Iconsource={SearchMinor}/>}onChange={updateText}label="Search tags"labelHiddenvalue={inputValue}placeholder="Search tags"autoComplete="off"/>}>{options.length>0?(<ListboxonSelect={updateSelection}>{optionsMarkup}</Listbox>):null}</Combobox></div>);}

Props

Want to help make this feature better? Pleaseshare your feedback.

interface ComboboxProps

activator React.ReactElement<&(||)&(|)>: The text field component to activate the Popover.
allowMultiple? boolean: Allows more than one option to be selected.
children? any: The content to display inside the popover.
preferredPosition? 'above'|'below'|'mostSpace': The preferred direction to open the popover.
willLoadMoreOptions? boolean: Whether or not more options are available to lazy load when the bottom of the listbox reached. Use the hasMoreResults boolean provided by the GraphQL API of the paginated data.
height? string: Height to set on the Popover Pane.
onScrolledToBottom? () =>void: Callback fired when the bottom of the lisbox is reached. Use to lazy load when listbox option data is paginated.
onClose? () =>void: Callback fired when the popover closes.

Anatomy

A diagram of the Combobox component showing the smaller primitive components it is composed of.

A combobox is made up of the following:

TextField: A text input that activates a popover displaying a list of options. As merchants type in the text field, the list of options is filtered by the input value. Options replace or add to the input value when selected.
Popover: An overlay containing a list of options.
Listbox: A list of options to filter and select or deselect.
Listbox.Option: The individual options to select or deselect. Check out thelistbox component documentationto learn how to compose it with various content.

最佳实践

TheComboboxcomponent should:

Be clearly labeled so the merchant knows what kind of options will be available
Not be used within a popover
Indicate a loading state to the merchant while option data is being populated
Order items in an intentional way so it’s easy for the merchant to find a specific value

Content guidelines

The input field forComboboxshould follow thecontent guidelinesfor text fields.

Sorting and filtering

Sorting

Item order should be intentional. Order them so it’s easy for the merchant to find a specific value. Some ways you can do this:

Sort options in alphabetical order
Display options based on how frequently the merchant selects an option

If multiple options can be selected, move selected items to the top of the list. If this doesn’t work for your context, you can override this behavior.

Filtering

By default, menu items are filtered based on whether or not they match the value of the textfield.
Filters arenotcase-sensitive by default.
You can apply custom filtering logic if the default behavior doesn’t make sense for your use case.

Patterns

Tags autocomplete

The tag multi-select input enables merchants to efficiently add or remove tags from a resource, like a product or an order. It uses the inline autocomplete combobox pattern to present merchants with an editable list of tags to browse and select from.

For an input field without suggested options,使用the text field component
For a list of selectable options not linked to an input field,使用the list box component

Accessibility

Structure

TheComboboxcomponent is based on theARIA 1.2 combobox pattern. It is a combination of a single-lineTextFieldand aPopover. The current implementation expects aListboxcomponent to be used.

TheComboboxpopover displays below the text field or other control by default so it is easy for merchants to discover and use. However, you can change the position with thepreferredPositionprop.

Comboboxfeatures can be challenging for merchants with visual, motor, and cognitive disabilities. Even when they’re built using best practices, these features can be difficult to use with some assistive technologies. Merchants should always be able to search, enter data, or perform other activities without relying on the combobox.

Do

Use combobox as progressive enhancement to make the interface easier to use for most merchants.

Don’t

Require that merchants make a selection from the combobox to complete a task.

Keyboard support

Give the combobox's text input keyboard focus with thetabkey (or转变+tabwhen tabbing backwards)