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.
Snippet
<Form.Group>
<labelhtmlFor="picker"id="picker-label">
Choose a fruit
</label>
<Pickeraria-labelledby="picker-label"id="picker">
<Optionkey="apple">Apple</Option>
<Optiondisabledkey="banana">
Banana
</Option>
<Optionkey="mangos">Mangos</Option>
<Optionkey="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.
Snippet
<Form.Group>
<labelhtmlFor="picker"id="picker-label">
Choose a fruit
</label>
<Pickeraria-labelledby="picker-label"id="picker"items={['Apple', 'Banana', 'Mangos']}
>
{(item) => <Optionkey={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.
Info
The 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.
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.
Warning
If 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.
Snippet
<Form.Group>
<labelhtmlFor="picker"id="picker-label">
Choose a fruit
</label>
<Pickeraria-labelledby="picker-label"id="picker"native>
<Optionkey="apple">Apple</Option>
<Optionkey="banana">Banana</Option>
<Optionkey="mangos">Mangos</Option>
</Picker>
</Form.Group>
Property to set the default value of active (uncontrolled).
defaultSelectedKey
React.Key|undefined
The initial selected key (uncontrolled).
direction
"bottom"|"top"|undefined= "bottom"
Direction the menu will render relative to the Picker.
disabled
boolean|undefined
Flag to indicate that the component is disabled.
id
string|undefined
The id of the component.
messages
{ itemSelected: string; itemDescribedby: string; } |undefined= {"itemDescribedby":"You are currently on a text element, inside of a list box.","itemSelected":"{0}, selected"}
Texts used for assertive messages to SRs.
native
boolean|undefined
Flag to make the component hybrid, when identified it is on a mobile
device it will use the native selector.
onActiveChange
InternalDispatch<boolean>|undefined
Callback for when the active state changes (controlled).
onSelectionChange
InternalDispatch<React.Key>|undefined
Callback calling when an option is selected.
placeholder
string|undefined= "Select an option"
Text that appears when you don’t have an item selected.
selectedKey
React.Key|undefined
The currently selected key (controlled).
shrink
boolean|undefined
Flag to make the picker only as wide as its contents.
width
number|undefined
Sets the width of the panel.
UNSAFE_menuClassName
string|undefined
Sets the className for the React.Portal Menu element.