SelectList

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, 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!

View SelectList stories

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.

disabledBehavior?

DisabledBehavior;

Whether disabledKeys applies to all interactions, or only selection.

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'

id?

string;

The element's unique identifier. See MDN.

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'

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.

onChange?

((keys: Selection) => void) | Dispatch<any>;

Handler that is called when the selection change.

onScroll?

(e: UIEvent<HTMLDivElement, UIEvent>) => void;

Handler that is called when a user scrolls. See MDN.

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.

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.

SelectList.Item

children?

ReactNode;

The children of the component. A function may be provided to alter the children based on component state.

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.

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.

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.

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.

ping?

string;

A space-separated list of URLs to ping when the link is followed. See MDN.

ref?

Ref<HTMLDivElement>;

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.

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: 7 minutes ago