errorMessage

The error message communicates an error for when the selection requirements aren't met, prompting a user to adjust what they had originally selected.

helpText

A picker can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field.

isError

A picker can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid.

isDisabled

A picker in a disabled state shows that an input field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later.

menuContainer

The picker menu is a menu element that is used to display the options for the picker. A picker menu can include menu items, menu dividers, and menu groups. A picker menu should never contain submenus, as doing so would render it inaccessible.

isRequired and necessityIndicator

Pickers can be marked as optional or required depending on the situation, using the necessityIndicator property.

For required pickers, you have two options:

• Text label: Display "(required)" after the label text
• Asterisk: Display an asterisk (*). If you use an asterisk, include hint text that explains what it means (e.g., "* indicates a required field")

For optional pickers, you have two options:

• Text label: Display "(optional)" after the label text
• No indicator: Show no indication at all

isQuiet

By default, pickers have a visible background. This style works best in a dense array of controls where the background helps to separate the input from the surrounding container, or to give visibility to isolated buttons.

Alternatively, quiet pickers can have no visible background. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read.

size

Pickers come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.

width

The width of a picker can be customized appropriately for its context. This option is not applicable to quiet pickers.

value

The value shows the option that a user has selected.

placeholder

Placeholder text provides hints about expected input values. It disappears once a user selects an option.

labelPosition

Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited.

label

Pickers should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These pickers without a visible label should still include an aria-label in HTML (depending on the context, "aria-label" or "aria-labelledby").