A Combobox combines a text input and a list of suggested (but not mandatory) values that appears when the user enters text into the text input. Combobox can be used to create features such as autocomplete, or to showcase popular choices.
Combobox is only available in the React API for Visage, not in the vanilla JS version.
Basic Combobox
For a typical Combobox, we provide a BasicCombobox convenience component.
It takes as children a set of ComboboxOption components, each of which needs a value prop. The value is what will be displayed in the popup of suggestions once the user starts typing.
If you want a suggestion to display the value plus some additional content (such as a Callout), you can give a ComboboxOption a child element of <ComboboxOptionText /> along with that additional content. This ComboboxOptionText child will display the actual value; the additional content will not be displayed inside the text input if the user picks this suggestion.
<BasicComboboxaria-labelledby="my-example-labeling-element"placeholder="Enter a fruit..."><ComboboxOption value="Apple" /><ComboboxOption value="Banana" /><ComboboxOption value="Orange" /><ComboboxOption value="Pineapple">🍍 <ComboboxOptionText /></ComboboxOption><ComboboxOption value="Kiwi">🥝 <ComboboxOptionText /></ComboboxOption></BasicCombobox>
full Combobox
If you can't use the BasicCombobox convenience component, you can also use the API for the actual Combobox that underlies it.
This allows you to put additional content inside the "popover" sub-component, notably a ComboboxPopoverTitle above the ComboboxList.
<Combobox aria-labelledby="my-example-labeling-element"><ComboboxInput /><ComboboxPopover><ComboboxPopoverTitle>Popular choices</ComboboxPopoverTitle><ComboboxList><ComboboxOption value="Apple" /><ComboboxOption value="Banana" /><ComboboxOption value="Orange" /><ComboboxOption value="Pineapple">🍍 <ComboboxOptionText /></ComboboxOption><ComboboxOption value="Kiwi">🥝 <ComboboxOptionText /></ComboboxOption></ComboboxList></ComboboxPopover></Combobox>
Combobox with Thumbnails
The Combobox popup can also display square thumbnails for each of the suggestions. Instead of ComboboxOption, use ComboboxOptionWithThumbnail. Each ComboboxOptionWithThumbnail should have two children:
a
ComboboxOptionThumbnailContainerholding a squareFluidImagea
ComboboxOptionTextContainerholding the<ComboboxOptionText />and any other content.
<Combobox aria-label="my example combobox"><ComboboxInput /><ComboboxPopover><ComboboxPopoverTitle>Popular choices</ComboboxPopoverTitle><ComboboxList><ComboboxOptionWithThumbnail value="Apple is a really long option whose contents will spill out onto the second row"><ComboboxOptionThumbnailContainer><FluidImage src="https://picsum.photos/100/100" alt="my thumbnail" /></ComboboxOptionThumbnailContainer><ComboboxOptionTextContainer><ComboboxOptionText /><Typography textSize={7} textColor="dark-grey">Fruit</Typography></ComboboxOptionTextContainer></ComboboxOptionWithThumbnail><ComboboxOptionWithThumbnail value="Banana"><ComboboxOptionThumbnailContainer><FluidImage src="https://picsum.photos/100/100" alt="my thumbnail" /></ComboboxOptionThumbnailContainer><ComboboxOptionTextContainer><ComboboxOptionText /><Typography textSize={7} textColor="dark-grey">Fruit</Typography></ComboboxOptionTextContainer></ComboboxOptionWithThumbnail><ComboboxOptionWithThumbnail value="Orange"><ComboboxOptionThumbnailContainer><FluidImage src="https://picsum.photos/100/100" alt="my thumbnail" /></ComboboxOptionThumbnailContainer><ComboboxOptionTextContainer><ComboboxOptionText /><Typography textSize={7} textColor="dark-grey">Fruit</Typography></ComboboxOptionTextContainer></ComboboxOptionWithThumbnail><ComboboxOptionWithThumbnail value="Pineapple"><ComboboxOptionThumbnailContainer><FluidImage src="https://picsum.photos/100/100" alt="my thumbnail" /></ComboboxOptionThumbnailContainer><ComboboxOptionTextContainer><ComboboxOptionText /><Typography textSize={7} textColor="dark-grey">Fruit</Typography></ComboboxOptionTextContainer></ComboboxOptionWithThumbnail><ComboboxOptionWithThumbnail value="Carrot"><ComboboxOptionThumbnailContainer><FluidImage src="https://picsum.photos/100/100" alt="my thumbnail" /></ComboboxOptionThumbnailContainer><ComboboxOptionTextContainer><ComboboxOptionText /><Typography textSize={7} textColor="dark-grey">Vegetable</Typography></ComboboxOptionTextContainer></ComboboxOptionWithThumbnail></ComboboxList></ComboboxPopover></Combobox>
Components
Visage's Combobox is built on top of the reach-ui third-party component. See the Reach documentation for full prop descriptions.