Listboxes allow a user to select a value or multiple values from a custom-styled dropdown.
Listboxes should only be used when multiselect or custom styles are needed. If you can get by with using the browser styles provided by the component, you should use it first.
While Listbox is similar to the component, they differ in that listboxes represent a selection by the user. Items in a listbox do not have their own individual actions. You can use the ListboxButton component to easily present a listbox in a popout with a button that matches the appearance of our component.
import { Listbox, ListboxButton, useSelect } from '@sproutsocial/racine'
( ) => {
const { value , onChange } = useSelect ( { initialValue : null } )
return (
< ListboxButton
minWidth = " 150px "
aria-label = " Select a fruit "
content = {
< Listbox onChange = { onChange } value = { value } width = " 200px " >
< Listbox.Group >
< Listbox.Item value = " Apple " > Apple </ Listbox.Item >
< Listbox.Item value = " Orange " > Orange </ Listbox.Item >
< Listbox.Item value = " Banana " > Banana </ Listbox.Item >
</ Listbox.Group >
</ Listbox >
}
>
{ value || 'Select a fruit' }
</ ListboxButton >
)
}
Show more
Properties Name Type Default Description Required? childrenReact.Nodevalue?string | string[]Any item(s) matching this value will be rendered in a selected state onChange(event) => ()Called whenever a new value is selected. innerRefReact.RefUsed if you need to compose Listbox with Downshift multiselectbooleanfalseWhether or not the listbox should allow multiple selections
Subcomponents Listbox group Groups are used to provide default padding and spacing around items, and can optionally render a visual label for a group of items.
< Listbox.Group title = " Fruit " >
< Box bg = " neutral.100 " p = { 400 } />
</ Listbox.Group >
Name Type Default Description Required? childrenReact.NodetitleReact.RefIf provided, a group header will be rendered in the listbox appearancedefault, flushdefaultUse the flush appearance if you’re using the listbox group with a title outside of a popout disabledbooleanfalseIf all of the items in a group are disabled, the group title should also be disabled
Listbox item Represents a unique value within a listbox. Selected items are indicated with a check icon and text.
< Box >
< Listbox.Item value = " Apple " > Apple </ Listbox.Item >
< Listbox.Item value = " Orange " selected >
Orange
</ Listbox.Item >
</ Box >
Name Type Default Description Required? childrenReact.NodedisabledbooleanfalsevaluestringelemBeforeReact.NodeA component to be rendered before the children of the menu item elemAfterReact.NodeA component to be rendered after the children of the menu item
Listbox checkbox A listbox item with a visible representing a selection.
< Listbox.Checkbox value = " Apple " > Apple </ Listbox.Checkbox >
Listbox radio A listbox item with a visible representing a selection.
< Listbox.Radio value = " Apple " > Apple </ Listbox.Radio >
Listbox filter input A special version of that can be used to allow the user to filter items within a listbox.
( ) => {
const { value , onChange } = useSelect ( { initialValue : null } )
return (
< ListboxButton
minWidth = " 200px "
aria-label = " Select a fruit "
content = {
< Listbox onChange = { onChange } value = { value } width = " 200px " >
< Listbox.Group >
< Listbox.FilterInput placeholder = " Filter items " mb = { 300 } />
< Listbox.Item value = " Apple " > Apple </ Listbox.Item >
< Listbox.Item value = " Orange " > Orange </ Listbox.Item >
< Listbox.Item value = " Banana " > Banana </ Listbox.Item >
</ Listbox.Group >
</ Listbox >
}
>
{ value || 'Select a fruit' }
</ ListboxButton >
)
}
Show more
Listbox divider A horizontal line with the “separator” role. Accepts the same props as
Recipes Changing the listbox button size ListboxButton offers a small and large size for matching the size of other elements in a form. The following example shows the small size:
( ) => {
const { value , onChange } = useSelect ( { initialValue : null } )
return (
< ListboxButton
minWidth = " 150px "
aria-label = " Select a fruit "
size = ' small '
content = {
< Listbox onChange = { onChange } value = { value } width = " 200px " >
< Listbox.Group >
< Listbox.Item value = " Apple " > Apple </ Listbox.Item >
< Listbox.Item value = " Orange " > Orange </ Listbox.Item >
< Listbox.Item value = " Banana " > Banana </ Listbox.Item >
</ Listbox.Group >
</ Listbox >
}
>
{ value || 'Select a fruit' }
</ ListboxButton >
)
}
Show more
Multiselect
( ) => {
const { value , onChange } = useMultiselect ( )
const currentOption =
value . length > 1 ? value . length + ' selected' : value . length ? value : null
return (
< ListboxButton
minWidth = " 150px "
aria-label = " Select a fruit "
content = {
< Listbox multiselect onChange = { onChange } value = { value } width = " 200px " >
< Listbox.Group >
< Listbox.Checkbox value = " Apple " > Apple </ Listbox.Checkbox >
< Listbox.Checkbox value = " Orange " > Orange </ Listbox.Checkbox >
< Listbox.Checkbox value = " Banana " > Banana </ Listbox.Checkbox >
</ Listbox.Group >
</ Listbox >
}
>
{ currentOption || 'Select a fruit' }
</ ListboxButton >
)
}
Show more
Groups
( ) => {
const { value , onChange } = useSelect ( { initialValue : null } )
return (
< ListboxButton
minWidth = " 150px "
aria-label = " Select a fruit "
content = {
< Listbox onChange = { onChange } value = { value } width = " 200px " >
< Listbox.Group title = " Fruit " >
< Listbox.Item value = " Apple " > Apple </ Listbox.Item >
< Listbox.Item value = " Orange " > Orange </ Listbox.Item >
< Listbox.Item value = " Banana " > Banana </ Listbox.Item >
</ Listbox.Group >
< Listbox.Group title = " More fruit " >
< Listbox.Item value = " Kiwi " > Kiwi </ Listbox.Item >
< Listbox.Item value = " Papaya " > Papaya </ Listbox.Item >
< Listbox.Item value = " Mango " > Mango </ Listbox.Item >
</ Listbox.Group >
</ Listbox >
}
>
{ value || 'Select a fruit' }
</ ListboxButton >
)
}
Show more
