Select API

Import

Cimpress UI exports three select-related components:

Select: main component that allows users to select one item from a collapsible list.
SelectItem: component that renders a single selectable item within a select.
SelectSection: component that groups related select items together under a section title.

import { Select, SelectItem, SelectSection } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Preview
Code

Favorite fruit (controlled)

Favorite fruit (uncontrolled)

import { Select, SelectItem, Stack, type Key } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [selectedKey, setSelectedKey] = useState<Key | null>('apple');

  return (
    <Stack gap={32}>
      <Select label="Favorite fruit (controlled)" selectedKey={selectedKey} onSelectionChange={setSelectedKey}>
        <SelectItem id="apple">Apple</SelectItem>
        <SelectItem id="banana">Banana</SelectItem>
        <SelectItem id="cherry">Cherry</SelectItem>
      </Select>

      <Select label="Favorite fruit (uncontrolled)" defaultSelectedKey="apple">
        <SelectItem id="apple">Apple</SelectItem>
        <SelectItem id="banana">Banana</SelectItem>
        <SelectItem id="cherry">Cherry</SelectItem>
      </Select>
    </Stack>
  );
}

Accessibility notes

Collapsible select list can be opened by focusing on the select trigger and pressing Enter, Space, Up Arrow, or Down Arrow.

Collapsible select list follows the ARIA listbox pattern. See the linked page for a list of available keyboard interactions.

Select requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

Collections

Select is a collection component. See our collection components guide to learn how to work with collections.

API reference

Select

Allows users to select one item from a collapsible list.

See select usage guidelines.

ref Ref<HTMLDivElement>: The ref type for this component.

SelectProps<T extends CollectionItem = CollectionItem>

isVirtualized boolean: Whether the list of options should be virtualized. Use this as a performance optimization for large lists.

Defaults to false .
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
label string: The content to display as the label.
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.
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.
name string: The name of the input element, used when submitting an HTML form. See MDN.
description string: A description for the field. Provides a hint such as specific requirements for what to choose.
error FieldError: An error message for the field.
validate (value: Key) => undefined | string | true | string[]: A function that returns an error message (or true) if a given value is invalid. Validation errors are displayed to the user when the form is submitted. For real-time validation, use the error prop instead.
children ReactNode | ((item: T) => ReactNode): The contents of the collection.
items Iterable<T, any, any>: The items to display in the collection.
onOpenChange (isOpen: boolean) => void: Method that is called when the open state of the menu changes.
autoComplete string: Describes the type of autocomplete functionality the input should provide if any. See MDN.
onFocus (e: FocusEvent<Element>) => void: Handler that is called when the element receives focus.
onBlur (e: FocusEvent<Element>) => void: Handler that is called when the element loses focus.
autoFocus boolean: Whether the element should receive focus on render.
isRequired boolean: Whether user input is required on the input before form submission.
isInvalid boolean: Whether the input value is invalid.
isDisabled boolean: Whether the input is disabled.
selectedKey null | Key: The currently selected key in the collection (controlled).
defaultSelectedKey Key: The initial selected key in the collection (uncontrolled).
onSelectionChange (key: null | Key) => void: Handler that is called when the selection changes.
onScroll (e: UIEvent<HTMLDivElement>) => void: Handler that is called when a user scrolls. See MDN.
placeholder string: Temporary text that occupies the select when it is empty.

Defaults to 'Select an item' (localized) .

StyleProps

margin Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

SelectItem

Renders a single list item within Select.

SelectItemProps

children * StringLikeChildren: The content to display as the label.
onHoverStart (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd (e: HoverEvent) => void: Handler that is called when a hover interaction ends.
id Key: The unique id of the item.
isDisabled boolean: Whether the item is disabled.

SelectSection

Groups list items within Select into a section.

SelectSectionProps<T extends CollectionItem>

title * string: The content to display as the section title.
id Key: The ID of the section. Has to be unique across all sections and items.
children ReactNode | ((item: T) => ReactNode): The contents of the collection.
items Iterable<T, any, any>: The items to display in the collection.