Skip to main contentSkip to search
Clay
  • Get Started
    • How to Use Clay
    • Composition Philosophy
    • How to Read This Documentation
    • Migrating From v2.x
    • Using Clay in JSPs
  • Components
    • Alert
    • Application Bar
    • Aspect Ratio
    • Autocomplete
    • Badge
    • Breadcrumb
    • Button Group
    • Buttons
    • Card
    • Chart
    • Color Picker
    • Data Provider
    • Date Picker
    • DropDown
    • Empty State
    • Form
      • Checkbox
      • Dual List Box
      • Input
      • Radio Group
      • Select
      • Select Box
      • Toggle Switch
    • Forms Hierarchy
    • Heading
    • Icon
    • Label
    • Layout
    • Link
    • List
    • Loading Indicator
    • Localized Input
    • Management Toolbar
    • Modal
    • Multi Select
    • Multi Step Nav
    • Nav
    • Navigation Bar
    • OverlayMask
    • Pagination
    • Pagination Bar
    • Panel
    • Picker
    • Popover
    • Progress Bar
    • Provider
    • Sidebar
    • Slider
    • Sticker
    • Table
    • Tabs
    • Text
    • Timelines
    • Time Picker
    • Toolbar
    • Tooltip
    • TreeView
    • Upper Toolbar
    • VerticalBar
    • Vertical Navigation
  • Contributing
  • CSS Framework
    • Paver
    • SCSS
    • Color
    • Grid
    • Content
      • Typography
      • C Kbd
    • Utilities
      • Accessibility
      • Autofit
      • Border
      • C Focus Inset
      • C Inner
      • Color Utilities
      • C Spacing Utilities
      • Display
      • Flex
      • Float
      • Inline Item
      • Overflow
      • Position
      • Shadow
      • Text
      • Vertical Align
      • Visibility
      • Width and Height
    • Playground
  • Examples
K
  • Docs
  • Sass API
  • Blog
  • Storybook
  • Codesandbox
  • Github
  • Use this menu to toggle between Atlas and Base Themes.

Picker

yarn add @clayui/core

A select is very similar to a dropdown visually but it let users select options from the panel and then represent the selection in the button.

  • Examples
  • API

Beta3.85.0CHANGELOGstorybook demos

  • Example
  • Introduction
  • Content
    • Static
    • Dynamic
  • Controlled and Uncontrolled component
  • Hybrid component

Example

Copied!
Code Sample (expand to see it)

Introduction

The Picker component is visually similar to a DropDown component but developed specifically for the user to select options from the menu but following the w3c accessibility recommendations.

Like the TreeView, VerticalBar and other components this is a middle-level component rather than a low-level or high-level component. Unlike a DropDown, the Picker has simplified APIs and OOTB features to follow accessibility patterns for a combobox-only but following the same APIs pattern and allowing flexibility to customize the content of the options and the trigger.

Content

Content rendered in the <Picker /> Menu can be done in two different ways, static and dynamic content just like in DropDown, the choice depends on the use case.

Static

Static content is when the <Picker /> options do not change during the lifecycle of the application or are hardcoded options.

<Form.Group>
	<label htmlFor="picker" id="picker-label">
		Choose a fruit
	</label>
	<Picker aria-labelledby="picker-label" id="picker">
		<Option key="apple">Apple</Option>
		<Option disabled key="banana">
			Banana
		</Option>
		<Option key="mangos">Mangos</Option>
		<Option key="blueberry">Blueberry</Option>
	</Picker>
</Form.Group>

Dynamic

Unlike static content, dynamic content is when the options can change during the lifecycle of the application or when the data comes from a service. Dynamic content rendering is data agnostic, this allows you to configure how to render the component options regardless of the chosen data structure.

<Form.Group>
	<label htmlFor="picker" id="picker-label">
		Choose a fruit
	</label>
	<Picker
		aria-labelledby="picker-label"
		id="picker"
		items={['Apple', 'Banana', 'Mangos']}
	>
		{(item) => <Option key={item}>{item}</Option>}
	</Picker>
</Form.Group>

Controlled and Uncontrolled component

As with any component in Clay, controlled and uncontrolled components are the ability to manage state in the parent or let Clay control the state of the component. You can read more about this in our blog.

For the <Picker /> component you can control the selectedKey and active states by adding a state to your component, this is only advisable when you need this information otherwise don't use it.

If you just need to set the initial state of the selectedKey, use the defaultSelectedKey property which is appropriate for that use case.

InfoThe selectedKey property is represented by the key property configured in the Option component, so the component can identify which value is selected and which should be shown in the trigger.

When the content rendering is dynamic and the data has id property defined, the component uses id instead of key.
function Example() {
	// Controlled
	const [active, setActive] = useState(false);

	// Controlled
	const [selectedKey, setSelectedKey] = useState('');

	return (
		<Form.Group>
			<label htmlFor="picker" id="picker-label">
				Choose a fruit
			</label>
			<Picker
				active={active}
				aria-labelledby="picker-label"
				id="picker"
				onActiveChange={setActive}
				onSelectionChange={setSelectedKey}
				selectedKey={selectedKey}
			>
				<Option key="apple">Apple</Option>
				<Option key="banana">Banana</Option>
				<Option key="mangos">Mangos</Option>
			</Picker>
		</Form.Group>
	);
}

Hybrid component

Native select for mobile devices offers a better experience compared to Picker in some cases. The Picker offers the possibility to render using the native selector of the browser of the device when it is detected that it is on a mobile device, by default this property is disabled but it can be enabled by setting the native property to true.

WarningIf the content of the Option component is not simple text, for it to work correctly set the property textValue to ensure that the component knows what the option label is.
<Form.Group>
	<label htmlFor="picker" id="picker-label">
		Choose a fruit
	</label>
	<Picker aria-labelledby="picker-label" id="picker" native>
		<Option key="apple">Apple</Option>
		<Option key="banana">Banana</Option>
		<Option key="mangos">Mangos</Option>
	</Picker>
</Form.Group>

How can this be improved? Create an issue!