SelectList
A component for displaying a list of interactive items, with support for keyboard navigation, single or multiple selection, and row actions.
The SelectList can be used to select multiple items from a list simultaneously. It provides a familiar interface where users can select multiple items.
Anatomy
A SelectList consists of a container element, with rows of data inside. The rows within a list may contain focusable elements or plain text content. If the list supports row selection, each row includes a selection indicator.
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".
Standard Ticket
Access to all main events • €49
VIP Ticket
Includes VIP lounge, free drinks • €129
Student Ticket
Valid student ID required • €29
Child Ticket
For children under 12 • €15
| Property | Type | Description |
|---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
The SelectList component is used to display a list of items that can be selected by the user. It supports both single and multiple selection modes, allowing users to choose one or more items from the list.
Built with accessibility in mind, it supports full keyboard navigation, making it easy to interact with using only the keyboard.
SelectList with multiple selection mode
If you want to allow users to select multiple items, you can set the selectionMode prop to multiple. This enables checkboxes for each item, allowing users to select or deselect multiple items at once.
You can also provide interactive actions for each item by using <SelectList.Action>, such as buttons or links, to perform specific actions on the selected items.
Preview
Code
Standard Ticket
€49
VIP Ticket
€129
Student Ticket
€29
Child Ticket
€15
Disabled behavior
The <SelectList> lets you disable certain items, which is helpful if you don’t want users to select them. You can use the disabledBehavior prop to control what happens with those disabled items. In the example below, we use disabledBehavior="selection". This means the disabled items can’t be selected and won’t show a selection indicator — but you can still use their actions (like buttons or links inside them).
Preview
Code
Standard Ticket
€49
VIP Ticket
€129
Student Ticket
€29
Child Ticket
€15
Props
Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
SelectList
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.
autoFocus?boolean | FocusStrategy;
Whether to auto focus the gridlist or an option.
children?ReactNode | ((item: object) => ReactNode);
The contents of the collection.
defaultSelectedKeys?"all" | Iterable<Key>;
The initial selected keys in the collection (uncontrolled).
dependencies?readonly any[]Values that should invalidate the item cache when using dynamic collections.
dir?string;
disabledBehavior?DisabledBehavior;
Whether
disabledKeys applies to all interactions, or only selection.Defaults to:
"all"disabledKeys?Iterable<Key>;
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
disallowEmptySelection?boolean;
Whether the collection allows empty selection.
disallowTypeAhead?boolean;
Whether typeahead navigation is disabled.
Defaults to:
"false"dragAndDropHooks?DragAndDropHooks;
The drag and drop hooks returned by
useDragAndDrop used to enable drag and drop behavior for the GridList.escapeKeyBehavior?"clearSelection" | "none";
Whether pressing the escape key should clear selection in the grid list or not.
Most experiences should not modify this option as it eliminates a keyboard user's ability to
easily clear selection. Only use if the escape key is being handled externally or should not
trigger selection clearing contextually.
Defaults to:
'clearSelection'hidden?boolean;
id?string;
The element's unique identifier. See MDN.
inert?boolean;
items?Iterable<object>;
Item objects in the collection.
keyboardNavigationBehavior?"arrow" | "tab";
Whether keyboard navigation to focusable elements within grid list items is
via the left/right arrow keys or the tab key.
Defaults to:
'arrow'lang?string;
layout?"stack" | "grid";
Whether the items are arranged in a stack or grid.
Defaults to:
'stack'onAction?(key: Key) => void;
Handler that is called when a user performs an action on an 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>;
onChange?((keys: Selection) => void) | Dispatch<any>;
Handler that is called when the selection change.
onClick?MouseEventHandler<HTMLDivElement>;
onClickCapture?MouseEventHandler<HTMLDivElement>;
onContextMenu?MouseEventHandler<HTMLDivElement>;
onContextMenuCapture?MouseEventHandler<HTMLDivElement>;
onDoubleClick?MouseEventHandler<HTMLDivElement>;
onDoubleClickCapture?MouseEventHandler<HTMLDivElement>;
onGotPointerCapture?PointerEventHandler<HTMLDivElement>;
onGotPointerCaptureCapture?PointerEventHandler<HTMLDivElement>;
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>;
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>;
ref?Ref<HTMLUListElement>;
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}renderEmptyState?(props: GridListRenderProps) => ReactNode;
Provides content to display when there are no items in the list.
selectedKeys?"all" | Iterable<Key>;
The currently selected keys in the collection (controlled).
selectionBehavior?SelectionBehavior;
How multiple selection should behave in the collection.
Defaults to:
"toggle"selectionMode?SelectionMode;
The type of selection that is allowed in the collection.
shouldSelectOnPressUp?boolean;
Whether selection should occur on press up instead of press down.
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";
SelectList.Item
children?ReactNode;
The children of the component. A function may be provided to alter the children based on component state.
dir?string;
disabled?boolean;
Whether the item is disabled.
Defaults to:
"false"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;
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.
ref?Ref<HTMLDivElement>;
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}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.
Alternative components
The SelectList is a versatile component that can be used in various scenarios where users need to select multiple items from a list. But there are alternative components that might be more suitable depending on your specific use case:
- Table: If you need to display tabular data with multiple selection capabilities, consider using the
<Table>component. It provides a structured layout for displaying data in rows and columns, along with selection features. - Stack: If you need to display a list of items with a more compact layout, consider using the
<Stack>component. It allows you to create a vertical stack of items, which can be useful for displaying lists with less emphasis on selection.
Last update: 14 days ago