Select
Base
The Select component allows you to select one or more items from a list of options.
Placeholder
Use the placeholder property to display a support text when no option is selected.
Options
Use the Select.Option subcomponent to define one or more options.
Option content
In addition to simple text, you can insert other components as children of Select.Option to create visually more complex options.
The label associated with an option is, by default, defined as the internal text (textContent) of the corresponding Select.Option. Therefore, when you need to create more elaborate options, use the Select.Option.Label subcomponent to explicitly define the label.
The Select.Option.Label subcomponent will always occupy the entire available horizontal space.
Disabled Option
Use the disabled property of the Select.Option subcomponent to disable an option.
Options group
Wrap the options in the Select.Group subcomponent to group them.
Collapsible group
Use the collapsible property of the Select.Group subcomponent so that, like the Accordion, its content can be collapsed or expanded.
Use the defaultClose property so that a collapsible group starts collapsed.
Separator
Use the Select.Divider subcomponent to separate options.
Multiple Selection
Use the multiple property to indicate that it is a Select component with multiple selection.
Initial value and state control
Use the defaultValue property to provide an initial value to the uncontrolled Select component, or use the value property to manage the value of the controlled Select.
The values assigned to the defaultValue or value of the Select must correspond to those existing in the value property of the Select.Option subcomponent. If the intention is that none of the available options are selected, it is necessary to provide an empty string in the case of single selection or an empty array in the case of multiple selection.
Uncontrolled
Use the defaultValue property to set the initial value of Select.
Controlled
You should create a state to manage the value through the value property when using the controlled Select component.
Disabled
Use the disabled property to prevent editing or any other user interaction with the Select component, making it disabled.
As a form field
Use the Select component within a Form.Control when it is used as a form field.
With error
Use the error property to indicate that the Select component has been filled with an invalid value. This will automatically apply a visual style to indicate the error to the user.
With success
Use the success property to indicate that the Select component has been filled with a valid value in a scenario where validation is required. This will apply positive visual feedback to the selection field.
Integration with Form.Control
As with other form components, the Select component is integrated with the Form.Control subcomponent and automatically receives the error and success properties through this integration.
Controlling dropdown opening and closing
Use the open property to control the opening and closing of the Select dropdown.
Customizations
Below are the main customization options available for the Select component.
Icon
Use the startIcon property to add an icon at the beginning of the input.
Selected values
Use the renderInputValue property to modify how the selected values are displayed in the input.
When using it, you will need to handle the rule of displaying the placeholder when there is no value. The style will be cleaned up, so if you want to keep the default style, you will need to wrap the result with the Select.Display component.
As tags
Use the Select.DisplayTag component as the value of the renderInputValue property to render the selected options as tags.
Access the component API documentation for more details on the expected values for the renderInputValue property and the properties of the Select.DisplayTag subcomponent.
Dropdown
Use the dropdownComponent property to provide a customized version of the Dropdown used to display the options.
Header and footer
Use the Select.Header and Select.Footer subcomponents to provide a header and a footer, respectively, for the Dropdown that displays the options.
Selection indicators
A selection indicator is a visual marker that signals, along with other styles, whether the option is selected or not. By default, only multiple selection Select components have this indicator, in this case, a Checkbox component.
Use the renderCheck property of the Select to customize this selection indicator.
Use the renderCheck property of the Select.Option subcomponent to customize this selection indicator for a particular option.
Indicators rendered by the renderCheck property of the Select.Option subcomponent take precedence over those rendered by the Select component.
Option content
As previously indicated, in addition to text, the Select.Option subcomponent can have other components as children, thus creating more elaborate options.
Below are some of the most common use cases:
With auxiliary text
Use the auxiliaryText property of the Select.Option.Label subcomponent to provide auxiliary text for the option.
With icon
You can add icons at the beginning and end of options.
With Avatar
You can add the Avatar component at the beginning of the options.
With Tag or Badge
You can add the Tag and Badge components at the end of the options.