Select
Dropdown for selecting an option among different options.
The <Select> is a form component that allows you to select one or more elements from a list of predefined options. It should be used with other form components in a <Form>.
Anatomy
A select contains a pressable button element with a down arrow. The lists of options opens per default below the button, if there is no space for it, it will open above. An option represent a possible choice the user can select.
Optional you have the choice to add a section to the options which helps divide the content of options in categories. You can have the possibility to add a supporting text as short description and/ or error message to the select itself. The description will be relplaced with the error message when an error throws. Also you can have a description for the options in the list.
Appearance
The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Variant
Size
The selected theme does not has any options for "variant" and "size".
Select the genre you want.
Genre
Select the genre you want.
| Property | Type | Description |
|---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
The select should be used within a form. It supports an optional description which can be used to provide more context about the field.
As with all form components, the label should always describe what the user expects to achieve. If additional informations is required you can use the description to give a short information for displaying these, or you can provide a placeholder which should represent what is to select.
Number of options
If there are very few options (e.g., 1-4), consider using a radio group instead. These can be easier for users to scan and select.
A select is typically suitable for a moderate number of options (e.g., 5-15). This keeps the list manageable and quick to navigate.
When there are too many options (e.g., more than 15-20), usability can suffer. Users might find it cumbersome to scroll through a long list. In such cases, consider alternative approaches like a autocomplete or combobox.
Do
Use a around 5-15 options for the select.
Don't
Don't use a select if there are less than 4 or more than 15 options to choose from.
With sections
When related options are present, organizing them into sections enhances clarity and usability. Grouping options provides additional context and helps users navigate choices more easily. This approach reduces complexity and allows for additional guidance when needed, ensuring a more intuitive experience.
This can be achieved by wrapping the options in the <Select.Section> component. A header is required for each section, which is set using the header prop.
Preview
Code
Genres
Item description
If you need to have primary and secondary content shown within an option, you can use our text component with the slot property and set it for the label and description to add a short description for secondary content, which provides more context for the certain selectable option.
Preview
Code
Permissions
Disabled keys
Sometimes depending on other settings it can be that a select needs to have disabled options to show up. For this case you can set keys disabled through the disabledKeys property.
Keep in mind that you always should write information why a certain option is disabled near the disabled option.
Preview
Code
Please select the shipping direction, not every country can be available.
Shipping direction
Please select the shipping direction, not every country can be available.
Multiselection
Sometimes you need to offer a way for users to select multiple options from a list, but you don't have much room in your layout. In these situations, enabling multiselection (selectionMode="multiple") on the <Select> is an effective approach. A common use case for this is when filtering a list of products. For instance, a user could select both a specific brand and a particular feature, and the dropdown would neatly contain both selections.
However, be mindful of the user experience when offering multiple selections. As more options are chosen, the display text will likely be truncated, hiding the full list of what's been selected. Note that for use cases requiring all selected options to be clearly visible, a dedicated Multiselect component might be a better choice.
Preview
Code
Amenities
Props
Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
Select
aria-describedby?string;
Identifies the element (or elements) that describes the object.
aria-details?string;
Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label?string;
Defines a string value that labels the current element.
aria-labelledby?string;
Identifies the element (or elements) that labels the current element.
autoComplete?string;
Describes the type of autocomplete functionality the input should provide if any. See MDN.
autoFocus?boolean;
Whether the element should receive focus on render.
children?ReactNode | ((item: T) => ReactNode);
Children of the select.
defaultOpen?boolean;
Sets the default open state of the menu.
defaultSelectedKey?Key;
The initial selected key in the collection (uncontrolled).
@deprecated
defaultValue?Key | Key[] | nullThe default value (uncontrolled).
description?string;
Set a description for the select.
dir?string;
disabled?boolean;
If the select should be disabled.
Defaults to:
"false"disabledKeys?Iterable<Key>;
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
error?boolean;
If the select should throw an error.
Defaults to:
"false"errorMessage?string | ((validation: ValidationResult) => string);
Set a error message for the select.
excludeFromTabOrder?boolean;
Whether to exclude the element from the sequential tab order. If true,
the element will not be focusable via the keyboard by tabbing. This should
be avoided except in rare scenarios where an alternative means of accessing
the element or its functionality via the keyboard is available.
form?string;
The
<form> element to associate the input with.
The value of this attribute must be the id of a <form> in the same document.
See MDN.hidden?boolean;
id?string;
The element's unique identifier. See MDN.
inert?boolean;
items?Iterable<T>;
Items of the select.
label?ReactNode;
Set a label for the select.
lang?string;
name?string;
The name of the input, used when submitting an HTML form.
onAnimationEnd?AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationStart?AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLDivElement>;
onAuxClick?MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?MouseEventHandler<HTMLDivElement>;
onBlur?(e: FocusEvent<Element, Element>) => void;
Handler that is called when the element loses focus.
onChange?(value: ValueType<M>) => void;
Handler that is called when the value changes.
onClick?MouseEventHandler<HTMLDivElement>;
onClickCapture?MouseEventHandler<HTMLDivElement>;
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onFocus?(e: FocusEvent<Element, Element>) => void;
Handler that is called when the element receives focus.
onFocusChange?(isFocused: boolean) => void;
Handler that is called when the element's focus status changes.
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onKeyDown?(e: KeyboardEvent) => void;
Handler that is called when a key is pressed.
onKeyUp?(e: KeyboardEvent) => void;
Handler that is called when a key is released.
onLostPointerCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onMouseDown?MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?MouseEventHandler<HTMLDivElement>;
onMouseEnter?MouseEventHandler<HTMLDivElement>;
onMouseLeave?MouseEventHandler<HTMLDivElement>;
onMouseMove?MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?MouseEventHandler<HTMLDivElement>;
onMouseOut?MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?MouseEventHandler<HTMLDivElement>;
onMouseOver?MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?MouseEventHandler<HTMLDivElement>;
onMouseUp?MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?MouseEventHandler<HTMLDivElement>;
onOpenChange?(isOpen: boolean) => void;
Method that is called when the open state of the menu changes.
onPointerCancel?PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?PointerEventHandler<HTMLDivElement>;
onPointerDown?PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?PointerEventHandler<HTMLDivElement>;
onPointerEnter?PointerEventHandler<HTMLDivElement>;
onPointerLeave?PointerEventHandler<HTMLDivElement>;
onPointerMove?PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?PointerEventHandler<HTMLDivElement>;
onPointerOut?PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?PointerEventHandler<HTMLDivElement>;
onPointerOver?PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?PointerEventHandler<HTMLDivElement>;
onPointerUp?PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?PointerEventHandler<HTMLDivElement>;
onScroll?UIEventHandler<HTMLDivElement>;
onScrollCapture?UIEventHandler<HTMLDivElement>;
onSelectionChange?(key: Key | null) => void;
Handler that is called when the selection changes.
@deprecated
onTouchCancel?TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?TouchEventHandler<HTMLDivElement>;
onTouchEnd?TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?TouchEventHandler<HTMLDivElement>;
onTouchMove?TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?TouchEventHandler<HTMLDivElement>;
onTouchStart?TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?TouchEventHandler<HTMLDivElement>;
onTransitionCancel?TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionRun?TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionStart?TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLDivElement>;
onWheel?WheelEventHandler<HTMLDivElement>;
onWheelCapture?WheelEventHandler<HTMLDivElement>;
open?boolean;
If the select list should be open.
Defaults to:
"false"placeholder?string;
Temporary text that occupies the select when it is empty.
Defaults to:
'Select an item' (localized)ref?Ref<HTMLButtonElement>;
Allows getting a ref to the component instance.
Once the component unmounts, React will set
ref.current to null
(or call the ref with null if you passed a callback ref).
@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}required?boolean;
If the select should be required.
Defaults to:
"false"selectedKey?Key | null;
The currently selected key in the collection (controlled).
@deprecated
selectionMode?SelectionMode;
Whether single or multiple selection is enabled.
Defaults to:
'single'slot?string | null;
A slot name for the component. Slots allow the component to receive props from a parent component.
An explicit
null value indicates that the local props completely override all props received from a parent.translate?"yes" | "no";
validate?(value: ValidationType<M>) => true | ValidationError | null;
A function that returns an error message if a given value is invalid.
Validation errors are displayed to the user when the form is submitted
if
validationBehavior="native". For realtime validation, use the isInvalid
prop instead.validationBehavior?"native" | "aria";
Whether to use native HTML form validation to prevent form submission
when the value is missing or invalid, or mark the field as required
or invalid via ARIA.
Defaults to:
'native'value?Key | Key[] | nullThe current value (controlled).
width?WidthProp;
Sets the width of the element. You can see allowed tokens here.
Select.Option
aria-label?string;
An accessibility label for this item.
children?ReactNode;
The children of the component
dir?string;
download?string | boolean;
Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
hidden?boolean;
href?string;
A URL to link to. See MDN.
hrefLang?string;
Hints at the human language of the linked URL. SeeMDN.
id?Key;
The unique id of the item.
inert?boolean;
isDisabled?boolean;
Whether the item is disabled.
lang?string;
onAction?() => void;
Handler that is called when a user performs an action on the item. The exact user event depends on
the collection's
selectionBehavior prop and the interaction modality.onAnimationEnd?AnimationEventHandler<HTMLDivElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationIteration?AnimationEventHandler<HTMLDivElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLDivElement>;
onAnimationStart?AnimationEventHandler<HTMLDivElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLDivElement>;
onAuxClick?MouseEventHandler<HTMLDivElement>;
onAuxClickCapture?MouseEventHandler<HTMLDivElement>;
onClick?(e: MouseEvent<FocusableElement, MouseEvent>) => void;
Not recommended – use
onPress instead. onClick is an alias for onPress
provided for compatibility with other libraries. onPress provides
additional event details for non-mouse interactions.onClickCapture?MouseEventHandler<HTMLDivElement>;
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onHoverChange?(isHovering: boolean) => void;
Handler that is called when the hover state changes.
onHoverEnd?(e: HoverEvent) => void;
Handler that is called when a hover interaction ends.
onHoverStart?(e: HoverEvent) => void;
Handler that is called when a hover interaction starts.
onLostPointerCapture?PointerEventHandler<HTMLDivElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
onMouseDown?MouseEventHandler<HTMLDivElement>;
onMouseDownCapture?MouseEventHandler<HTMLDivElement>;
onMouseEnter?MouseEventHandler<HTMLDivElement>;
onMouseLeave?MouseEventHandler<HTMLDivElement>;
onMouseMove?MouseEventHandler<HTMLDivElement>;
onMouseMoveCapture?MouseEventHandler<HTMLDivElement>;
onMouseOut?MouseEventHandler<HTMLDivElement>;
onMouseOutCapture?MouseEventHandler<HTMLDivElement>;
onMouseOver?MouseEventHandler<HTMLDivElement>;
onMouseOverCapture?MouseEventHandler<HTMLDivElement>;
onMouseUp?MouseEventHandler<HTMLDivElement>;
onMouseUpCapture?MouseEventHandler<HTMLDivElement>;
onPointerCancel?PointerEventHandler<HTMLDivElement>;
onPointerCancelCapture?PointerEventHandler<HTMLDivElement>;
onPointerDown?PointerEventHandler<HTMLDivElement>;
onPointerDownCapture?PointerEventHandler<HTMLDivElement>;
onPointerEnter?PointerEventHandler<HTMLDivElement>;
onPointerLeave?PointerEventHandler<HTMLDivElement>;
onPointerMove?PointerEventHandler<HTMLDivElement>;
onPointerMoveCapture?PointerEventHandler<HTMLDivElement>;
onPointerOut?PointerEventHandler<HTMLDivElement>;
onPointerOutCapture?PointerEventHandler<HTMLDivElement>;
onPointerOver?PointerEventHandler<HTMLDivElement>;
onPointerOverCapture?PointerEventHandler<HTMLDivElement>;
onPointerUp?PointerEventHandler<HTMLDivElement>;
onPointerUpCapture?PointerEventHandler<HTMLDivElement>;
onPress?(e: PressEvent) => void;
Handler that is called when the press is released over the target.
onPressChange?(isPressed: boolean) => void;
Handler that is called when the press state changes.
onPressEnd?(e: PressEvent) => void;
Handler that is called when a press interaction ends, either
over the target or when the pointer leaves the target.
onPressStart?(e: PressEvent) => void;
Handler that is called when a press interaction starts.
onPressUp?(e: PressEvent) => void;
Handler that is called when a press is released over the target, regardless of
whether it started on the target or not.
onScroll?UIEventHandler<HTMLDivElement>;
onScrollCapture?UIEventHandler<HTMLDivElement>;
onTouchCancel?TouchEventHandler<HTMLDivElement>;
onTouchCancelCapture?TouchEventHandler<HTMLDivElement>;
onTouchEnd?TouchEventHandler<HTMLDivElement>;
onTouchEndCapture?TouchEventHandler<HTMLDivElement>;
onTouchMove?TouchEventHandler<HTMLDivElement>;
onTouchMoveCapture?TouchEventHandler<HTMLDivElement>;
onTouchStart?TouchEventHandler<HTMLDivElement>;
onTouchStartCapture?TouchEventHandler<HTMLDivElement>;
onTransitionCancel?TransitionEventHandler<HTMLDivElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionEnd?TransitionEventHandler<HTMLDivElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionRun?TransitionEventHandler<HTMLDivElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLDivElement>;
onTransitionStart?TransitionEventHandler<HTMLDivElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLDivElement>;
onWheel?WheelEventHandler<HTMLDivElement>;
onWheelCapture?WheelEventHandler<HTMLDivElement>;
ping?string;
A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy?HTMLAttributeReferrerPolicy;
How much of the referrer to send when following the link. See MDN.
rel?string;
The relationship between the linked resource and the current page. See MDN.
routerOptions?undefined;
Options for the configured client side router.
target?HTMLAttributeAnchorTarget;
The target window for the link. See MDN.
textValue?string;
A string representation of the item's contents, used for features like typeahead.
translate?"yes" | "no";
value?object;
The object value that this item represents. When using dynamic collections, this is set automatically.
Select.Section
aria-label?string;
An accessibility label for the section.
childrenReactNode;
Children of the section.
dependencies?readonly any[]Values that should invalidate the item cache when using dynamic collections.
dir?string;
headerReactNode;
Section header to display.
hidden?boolean;
id?Key;
The unique id of the section.
inert?boolean;
items?Iterable<object>;
Item objects in the section.
lang?string;
onAnimationEnd?AnimationEventHandler<HTMLElement>;
onAnimationEndCapture?AnimationEventHandler<HTMLElement>;
onAnimationIteration?AnimationEventHandler<HTMLElement>;
onAnimationIterationCapture?AnimationEventHandler<HTMLElement>;
onAnimationStart?AnimationEventHandler<HTMLElement>;
onAnimationStartCapture?AnimationEventHandler<HTMLElement>;
onAuxClick?MouseEventHandler<HTMLElement>;
onAuxClickCapture?MouseEventHandler<HTMLElement>;
onClick?MouseEventHandler<HTMLElement>;
onClickCapture?MouseEventHandler<HTMLElement>;
onContextMenu?MouseEventHandler<HTMLElement>;
onContextMenuCapture?MouseEventHandler<HTMLElement>;
onDoubleClick?MouseEventHandler<HTMLElement>;
onDoubleClickCapture?MouseEventHandler<HTMLElement>;
onGotPointerCapture?PointerEventHandler<HTMLElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLElement>;
onLostPointerCapture?PointerEventHandler<HTMLElement>;
onLostPointerCaptureCapture?PointerEventHandler<HTMLElement>;
onMouseDown?MouseEventHandler<HTMLElement>;
onMouseDownCapture?MouseEventHandler<HTMLElement>;
onMouseEnter?MouseEventHandler<HTMLElement>;
onMouseLeave?MouseEventHandler<HTMLElement>;
onMouseMove?MouseEventHandler<HTMLElement>;
onMouseMoveCapture?MouseEventHandler<HTMLElement>;
onMouseOut?MouseEventHandler<HTMLElement>;
onMouseOutCapture?MouseEventHandler<HTMLElement>;
onMouseOver?MouseEventHandler<HTMLElement>;
onMouseOverCapture?MouseEventHandler<HTMLElement>;
onMouseUp?MouseEventHandler<HTMLElement>;
onMouseUpCapture?MouseEventHandler<HTMLElement>;
onPointerCancel?PointerEventHandler<HTMLElement>;
onPointerCancelCapture?PointerEventHandler<HTMLElement>;
onPointerDown?PointerEventHandler<HTMLElement>;
onPointerDownCapture?PointerEventHandler<HTMLElement>;
onPointerEnter?PointerEventHandler<HTMLElement>;
onPointerLeave?PointerEventHandler<HTMLElement>;
onPointerMove?PointerEventHandler<HTMLElement>;
onPointerMoveCapture?PointerEventHandler<HTMLElement>;
onPointerOut?PointerEventHandler<HTMLElement>;
onPointerOutCapture?PointerEventHandler<HTMLElement>;
onPointerOver?PointerEventHandler<HTMLElement>;
onPointerOverCapture?PointerEventHandler<HTMLElement>;
onPointerUp?PointerEventHandler<HTMLElement>;
onPointerUpCapture?PointerEventHandler<HTMLElement>;
onScroll?UIEventHandler<HTMLElement>;
onScrollCapture?UIEventHandler<HTMLElement>;
onTouchCancel?TouchEventHandler<HTMLElement>;
onTouchCancelCapture?TouchEventHandler<HTMLElement>;
onTouchEnd?TouchEventHandler<HTMLElement>;
onTouchEndCapture?TouchEventHandler<HTMLElement>;
onTouchMove?TouchEventHandler<HTMLElement>;
onTouchMoveCapture?TouchEventHandler<HTMLElement>;
onTouchStart?TouchEventHandler<HTMLElement>;
onTouchStartCapture?TouchEventHandler<HTMLElement>;
onTransitionCancel?TransitionEventHandler<HTMLElement>;
onTransitionCancelCapture?TransitionEventHandler<HTMLElement>;
onTransitionEnd?TransitionEventHandler<HTMLElement>;
onTransitionEndCapture?TransitionEventHandler<HTMLElement>;
onTransitionRun?TransitionEventHandler<HTMLElement>;
onTransitionRunCapture?TransitionEventHandler<HTMLElement>;
onTransitionStart?TransitionEventHandler<HTMLElement>;
onTransitionStartCapture?TransitionEventHandler<HTMLElement>;
onWheel?WheelEventHandler<HTMLElement>;
onWheelCapture?WheelEventHandler<HTMLElement>;
translate?"yes" | "no";
value?object;
The object value that this section represents. When using dynamic collections, this is set automatically.
Alternative components
Autocomplete: A searchfield that displays a dynamic list of suggestions. Useful when there are more than 15 options and you need to search for a specific value.
Combobox: A text field that allows the user to select values from a provided items array. Useful when there are mote than 15 options.
Radio: Component which allows to select only one option from a list. Use it if you have less than 5 options.
Related
Last update: 2 days ago