Skip to main content

​
About Visual Picker

Visual Picker enhances radio buttons and checkboxes with larger, more visual selection areas. Use it when you want to make selection options more prominent and easier to click, especially for important choices or when displaying options with icons or images.

​
Components

  • VisualPickerRadioGroup - Radio button group container
  • VisualPickerRadio - Individual radio option
  • VisualPickerCheckboxGroup - Checkbox group container
  • VisualPickerCheckbox - Individual checkbox option

​
Installation

yarn add @twilio-paste/visual-picker

​
Usage

​
Radio Group

import { VisualPickerRadioGroup, VisualPickerRadio } from '@twilio-paste/visual-picker';

const MyRadioGroup = () => {
  const [value, setValue] = React.useState('option1');
  
  return (
    <VisualPickerRadioGroup
      legend="Choose an option"
      name="options"
      value={value}
      onChange={setValue}
    >
      <VisualPickerRadio value="option1">
        Option 1
      </VisualPickerRadio>
      <VisualPickerRadio value="option2">
        Option 2
      </VisualPickerRadio>
      <VisualPickerRadio value="option3">
        Option 3
      </VisualPickerRadio>
    </VisualPickerRadioGroup>
  );
};

​
Checkbox Group

import { VisualPickerCheckboxGroup, VisualPickerCheckbox } from '@twilio-paste/visual-picker';

const MyCheckboxGroup = () => {
  const [selected, setSelected] = React.useState([]);
  
  return (
    <VisualPickerCheckboxGroup
      legend="Select features"
      name="features"
    >
      <VisualPickerCheckbox
        checked={selected.includes('feature1')}
        onChange={(e) => {
          // handle change
        }}
      >
        Feature 1
      </VisualPickerCheckbox>
      <VisualPickerCheckbox
        checked={selected.includes('feature2')}
        onChange={(e) => {
          // handle change
        }}
      >
        Feature 2
      </VisualPickerCheckbox>
    </VisualPickerCheckboxGroup>
  );
};

​
Props

​
VisualPickerRadioGroup

​
VisualPickerRadio

​
VisualPickerCheckboxGroup

​
VisualPickerCheckbox

​
Orientation

Control the layout with the orientation prop:

​
Vertical (default)

<VisualPickerRadioGroup
  orientation="vertical"
  legend="Choose"
  name="options"
  value={value}
  onChange={setValue}
>
  {/* options stack vertically */}
</VisualPickerRadioGroup>

​
Horizontal

<VisualPickerRadioGroup
  orientation="horizontal"
  legend="Choose"
  name="options"
  value={value}
  onChange={setValue}
>
  {/* options laid out horizontally */}
</VisualPickerRadioGroup>

​
With Icons

Enhance options with icons: 
import { ProductMessagingIcon, ProductVoiceIcon } from '@twilio-paste/icons/esm';

<VisualPickerRadioGroup legend="Choose product" name="product" value={value} onChange={setValue}>
  <VisualPickerRadio value="messaging">
    <ProductMessagingIcon decorative />
    <div>Messaging</div>
  </VisualPickerRadio>
  <VisualPickerRadio value="voice">
    <ProductVoiceIcon decorative />
    <div>Voice</div>
  </VisualPickerRadio>
</VisualPickerRadioGroup>

​
Error State

Show validation errors: 
<VisualPickerRadioGroup
  legend="Choose an option"
  name="options"
  value={value}
  onChange={setValue}
  errorText="Please select an option"
>
  {/* options */}
</VisualPickerRadioGroup>

​
Disabled State

Disable the entire group: 
<VisualPickerRadioGroup
  legend="Choose an option"
  name="options"
  value={value}
  onChange={setValue}
  disabled
>
  {/* options */}
</VisualPickerRadioGroup>

​
Accessibility

  • Uses semantic fieldset/legend structure
  • Proper radio/checkbox ARIA attributes
  • Keyboard navigation support
  • Error messages linked with aria-describedby
  • Focus indicators on keyboard navigation
  • Legend provides context for the group

​
When to Use

​
Use Visual Picker when:

  • Making important selections more prominent
  • Options include icons or images
  • You have 2-5 options to choose from
  • Selection is a primary action on the page

​
Use standard Radio/Checkbox when:

  • You have many options (6+)
  • Options are simple text labels
  • Space is constrained
  • Selection is secondary to other actions

​
Related components

Build docs developers (and LLMs) love

Get started for freeTalk to us