enact logoEnact
Edit on GitHub

sandstone/Picker

A component for selecting values from a list of values.

import Picker from '@enact/sandstone/Picker';

Members

PickerComponent

A Picker component that allows selecting values from a list of values.

By default, Picker maintains the state of its value property. Supply the defaultValue property to control its initial value. If you wish to directly control updates to the component, supply a value to value at creation time and update it in response to onChange events.

import Picker from '@enact/sandstone/Picker';
Properties
defaultValue
Number

Default index of the selected child.

Note: Changing defaultValue after initial render has no effect.

PickerBaseComponent

The base Picker component.

This version is not spottable.

import {PickerBase} from '@enact/sandstone/Picker';
Properties
children •
Node

Picker value list.

aria-valuetext
String

The aria-valuetext for the picker.

By default, aria-valuetext is set to the current selected child text.

changedBy
'enter''arrow'

Determines which key to adjust the picker's value for the joined horizontal one.

  • 'enter' allows the user to use the enter key to adjust the picker's value

  • 'arrow' allows the user to use the left or right keys to adjust the picker's value.

The default value for joined horizontal picker is 'enter'. If orientation is 'vertical' or joined is undefined or is false, this prop is ignored.

css
Object

Customizes the component by mapping the supplied collection of CSS class names to the corresponding internal elements and states of this component.

The following classes are supported:

  • title - The title component class

  • inlineTitle - The title component class when inlineTitle is true

data-webos-voice-labels-ext
ArrayNumberArrayString

The voice control labels for the children.

By default, data-webos-voice-labels-ext is generated from children. However, if children is not an array of numbers or strings, data-webos-voice-labels-ext should be set to an array of labels.

decrementIcon
String

A custom icon for the decrementer.

All strings supported by Icon are supported. Without a custom icon, the default is used, and is automatically changed when the orientation is changed.

disabled
Boolean

Disables the picker.

incrementIcon
String

A custom icon for the incrementer.

All strings supported by Icon are supported. Without a custom icon, the default is used, and is automatically changed when the orientation is changed.

inlineTitle
Boolean

Applies inline styling to the title.

joined
Boolean

Allows the user to use the arrow keys or enter key to adjust the picker's value.

Key presses are captured in the directions of the increment and decrement buttons but others are unaffected. A non-joined Picker allows navigation in any direction, but requires individual ENTER presses on the incrementer and decrementer buttons. Pointer interaction is the same for both formats.

marqueeDisabled
Boolean

Disables marqueeing of items.

By default, each picker item is wrapped by a Marquee. When this is set, the items will not be wrapped.

noAnimation
Boolean

Disables transition animation.

onChange
Function

Called when the value changes.

orientation
'horizontal''vertical'

Orientation of the picker.

Controls whether the buttons are arranged horizontally or vertically around the value.

reverse
Boolean

When true, the picker buttons operate in the reverse direction such that pressing up/left decrements the value and down/right increments the value. This is more natural for vertical lists of text options where "up" implies a spatial change rather than incrementing the value.

If this prop is omitted, it will be determined by orientation. For example, if orientation is vertical, reverse is true. Conversely, if orientation is horizontal, reverse is false.

title
String

The primary text of the Picker.

The screen readers read out the title text when the joined prop is false

type
'number''string'

The type of picker. It determines the aria-label for the next and previous buttons.

Depending on the type, joined, decrementAriaLabel, and incrementAriaLabel, the screen readers read out differently when Spotlight is on the next button, the previous button, or the picker itself.

For example, if Spotlight is on the next button, the joined prop is false, and aria label props(decrementAriaLabel and incrementAriaLabel) are not defined, then the screen readers read out as follows. 'string' type: 'next item' 'number' type: 'press ok button to increase the value'

Default: 'string'
value
Number

Index of the selected child.

Default: 0
width
Number'small''medium''large'

The width of the picker.

A number can be used to set the minimum number of characters to be shown. Setting a number to less than the number of characters in the longest value will cause the width to grow for the longer values.

A string can be used to select from pre-defined widths:

  • 'small' - numeric values

  • 'medium' - single or short words

  • 'large' - maximum-sized pickers taking full width of its parent

By default, the picker will size according to the longest valid value.

wrap
Boolean

Allows picker to continue from the start of the list after it reaches the end and vice-versa.

ArrayBooleanFunctionModuleNumberObjectString