Visual Picker is a selection component that allows users to select from a set of options. It is ideal to use in situations where users need to be able to see and compare different options before making a selection.
This component is built on top of Radio Group and Checkbox guidelines.
Visual Picker follows the same accessibility guidelines as Radio Group and Checkbox.
Like all input elements, both Radio and Checkbox Visual Pickers require a group label that describes the collection. Provide an accessible label using the legend prop on VisualPickerRadioGroup or VisualPickerCheckboxGroup. The grouping should be visually implicit, but a description still needs to be provided for assistive technology.
Always use the labelText prop on VisualPickerRadio and VisualPickerCheckbox to provide a descriptive string for each option.
When focused on a Visual Picker Radio control, use arrow keys to navigate to the other radios. When focused on a Visual Picker Checkbox control, use the tab key to navigate to the other checkboxes.
Use a Visual Picker Radio when a user must select a single option.
Vertical is the default orientation for Visual Picker.
Use the horizontal Visual Picker when more complex visuals will help users compare information. Avoid using horizontal if there are more than 3 options.
Use a Visual Picker Checkbox when a user can select multiple options.
Vertical is the default orientation for Visual Picker.
Use the horizontal Visual Picker when more complex visuals will help users compare information. Avoid using horizontal if there are more than 3-4 options.
Internationalizing Visual Picker is the same for both Radio and Checkbox. To internationalize, provide translated text as children. The only exception to this is the required dot in the legend of a required Visual Picker. To change the required dot's text, use the i18nRequiredLabel prop. You can hover over the required dot to see the translated string.
Use a Visual Picker with a pre-checked value only if:
- The default value would not cause harm if accidentally used.
- You don’t mind collecting biased data. Defaulting to a value biases or alters the experience so that your data may be skewed.
- The user doesn't need to make an explicit choice for safety, security, or legal reasons.
If you do apply a pre-checked value, make the checked option the first option.
Use a Disabled Visual Picker to show users that they can’t interact with it. When disabling an item, set all text colors to color-text-weak and gray out any other content.
If the selected items don't pass the group validation requirements, use the errorText prop to show an inline error Help Text message below the group.
For simple required field errors, consider the following formats depending on the use case:
| Situation | Recommended phrasing |
|---|---|
| Options are not nouns. | Select an option. |
| Options are nouns. | Select a [noun in group label]. |
For additional guidance on how to compose error messages, refer to the error state pattern.
Refer to the Radio and Checkbox composition notes for general guidance. Due to the visual nature of the component, avoid including more than two sentences in description text.
Visual Picker Radios and Checkboxes are sized based on their contents. In order to control and standardize the size of all pickers within a group, pass equally sized children to each picker.