Skip to content

Switcher

Props

API reference for Switcher. For usage examples, see the React tab.

Switcher.Root

NameTypeDefault
allowsEmptyCollectionboolean

Whether the select should be allowed to be open when the collection is empty.

childrenChildrenOrFunction<SelectRenderProps>

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

defaultOpenboolean

Sets the default open state of the menu.

disabledKeysIterable<Key>

The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

isDisabledboolean

Whether the input is disabled.

isOpenboolean

Sets the open state of the menu.

shouldCloseOnSelectboolean

Whether the Select should close when an item is selected. Defaults to true if selectionMode is single, false otherwise.

Switcher.Item

NameTypeDefault
childrenChildrenOrFunction<ListBoxItemRenderProps>

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

downloadstring | boolean

Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN (opens in new tab).

hrefstring

A URL to link to. See MDN (opens in new tab).

hrefLangstring

Hints at the human language of the linked URL. SeeMDN (opens in new tab).

isDisabledboolean

Whether the item is disabled.

pingstring

A space-separated list of URLs to ping when the link is followed. See MDN (opens in new tab).

referrerPolicyHTMLAttributeReferrerPolicy

How much of the referrer to send when following the link. See MDN (opens in new tab).

relstring

The relationship between the linked resource and the current page. See MDN (opens in new tab).

routerOptionsundefined

Options for the configured client side router.

targetHTMLAttributeAnchorTarget

The target window for the link. See MDN (opens in new tab).

textValuestring

A string representation of the item's contents, used for features like typeahead.

Switcher.LeadingIcon

NameTypeDefault
aboutstring
accessKeystring
autoSavestring
childrenReactNode
colorstring
contentstring
contextMenustring
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }
datatypestring
defaultCheckedboolean
exportpartsstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/exportparts (opens in new tab)

inlistany
inputMode"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"

Hints at the type of data that might be entered by the user while editing the element or its contents

See: https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute (opens in new tab)

itemIDstring
itemPropstring
itemRefstring
itemScopeboolean
itemTypestring
partstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part (opens in new tab)

prefixstring
propertystring
radioGroupstring
relstring
resourcestring
resultsnumber
revstring
securitystring
titlestring
typeofstring
unselectable"off" | "on"
vocabstring

Switcher.List

NameTypeDefault
children((item: T) => ReactNode) | ReactNode

The contents of the collection.

dependenciesreadonly any[]

Values that should invalidate the item cache when using dynamic collections.

filter((textValue: string, inputValue: string, node: Node<T>) => boolean)

When provided, renders a search field that filters list items via Autocomplete. Pass a filter from useFilter, e.g. const { contains } = useFilter({ sensitivity: "base" }).

gridColumnsnumber2

Number of columns when layout="grid". Ignored when layout is "stack".

itemsIterable<T>

Item objects in the collection.

layoutSwitcherLayoutstack

Layout of the list within the popover. - stack — vertical list; popover is at least as wide as the trigger and may grow to fit list content - grid — uses ListBox grid layout (gridColumns defaults to 2). The popover is at least as wide as the trigger and grows to fit the grid.

maxHeightnumber500

Maximum height of the popover containing the list, in pixels.

renderEmptyState((props: ListBoxRenderProps) => ReactNode)

Provides content to display when there are no items in the list.

searchAriaLabelstringSearch

Accessible name for the search field when no visible label is rendered. Only used when filter is provided.

searchPlaceholderstring

Placeholder text for the search field. Only used when filter is provided.

shouldFocusOnHoverboolean

Whether options should be focused when the user hovers over them.

shouldFocusWrapboolean

Whether focus should wrap around when the end/start is reached.

shouldSelectOnPressUpboolean

Whether selection should occur on press up instead of press down.

sizeListBoxSizemd

Controls list item height, padding, and label typography.

Switcher.Trigger

NameTypeDefault
childrenReactNode
isDisabledboolean

Whether the button is disabled.

isPendingboolean

Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers.

leadingIconReactNode

Icon element that renders at the start of the trigger, before the value.

size"lg" | "md" | "sm""md"

Determines the size of the trigger. - sm — 32px height, 8px inline / 4px block padding, 14px label - md — 40px height, 8px padding, 16px label - lg — 48px height, 12px padding, 16px label

Switcher.Value

NameTypeDefault
aboutstring
accessKeystring
autoSavestring
childrenChildrenOrFunction<SelectValueRenderProps<T>>

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

colorstring
contentstring
contextMenustring
dangerouslySetInnerHTML{ __html: string | TrustedHTML; }
datatypestring
defaultCheckedboolean
exportpartsstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/exportparts (opens in new tab)

inlistany
inputMode"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url"

Hints at the type of data that might be entered by the user while editing the element or its contents

See: https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute (opens in new tab)

itemIDstring
itemPropstring
itemRefstring
itemScopeboolean
itemTypestring
partstring

See: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/part (opens in new tab)

prefixstring
propertystring
radioGroupstring
relstring
resourcestring
resultsnumber
revstring
securitystring
titlestring
typeofstring
unselectable"off" | "on"
vocabstring