Choice Group

Use Choice Group...

When more content flexibility is needed than Radio Group or Checkbox Group can provide.
For selectable, button-like options (ChoiceButton and ChoiceIconButton).
For rich content in a selectable container (ChoiceCard).
For selecting SWAN tile components (ChoiceTile).
For selectable color swatches (ChoiceColorSwatch).

Don't use Choice Group...

For simple text-only radio or checkbox lists. Use Radio Group or Checkbox Group instead.
For a standalone, independent selection. Use Checkbox instead.

Selection Mode

Single

Use selectionMode=”single” to only allow one selection from the group.

<ChoiceGroup selectionMode="single" defaultSelectedValue="a">
  <ChoiceButton value="a">Option A</ChoiceButton>
  <ChoiceButton value="b">Option B</ChoiceButton>
  <ChoiceButton value="c">Option C</ChoiceButton>
</ChoiceGroup>

<ChoiceGroup selectionMode="single" defaultSelectedValue="a">
  <ChoiceButton value="a">Option A</ChoiceButton>
  <ChoiceButton value="b">Option B</ChoiceButton>
  <ChoiceButton value="c">Option C</ChoiceButton>
</ChoiceGroup>

Multiple

Use selectionMode=”multiple” to only multiple selections from the group.

<ChoiceGroup selectionMode="multiple" defaultSelectedValues={['a', 'b']}>
  <ChoiceButton value="a">Option A</ChoiceButton>
  <ChoiceButton value="b">Option B</ChoiceButton>
  <ChoiceButton value="c">Option C</ChoiceButton>
</ChoiceGroup>

<ChoiceGroup selectionMode="multiple" defaultSelectedValues={['a', 'b']}>
  <ChoiceButton value="a">Option A</ChoiceButton>
  <ChoiceButton value="b">Option B</ChoiceButton>
  <ChoiceButton value="c">Option C</ChoiceButton>
</ChoiceGroup>

Disabled

Use disabled on any Choice subcomponent to prevent it from being selected or deselected. To disable the entire group, use disabled on each item.

<ChoiceGroup selectionMode="single" aria-label="Disabled example">
  <ChoiceButton value="a">Option A</ChoiceButton>
  <ChoiceButton value="b">Option B</ChoiceButton>
  <ChoiceButton value="c" disabled>
    Option C
  </ChoiceButton>
</ChoiceGroup>

<ChoiceGroup selectionMode="single" aria-label="Disabled example">
  <ChoiceButton value="a">Option A</ChoiceButton>
  <ChoiceButton value="b">Option B</ChoiceButton>
  <ChoiceButton value="c" disabled>
    Option C
  </ChoiceButton>
</ChoiceGroup>

Required

Single

Use required on a single Choice subcomponent in the Choice Group to indicate that an option must be selected.

<ChoiceGroup selectionMode="single" aria-label="Required example">
  <ChoiceIconButton value="left" tooltip="Left align" required>
    <Icon iconType="alignLeft" />
  </ChoiceIconButton>
  <ChoiceIconButton value="center" tooltip="Center">
    <Icon iconType="alignCenter" />
  </ChoiceIconButton>
  <ChoiceIconButton value="right" tooltip="Right align">
    <Icon iconType="alignRight" />
  </ChoiceIconButton>
</ChoiceGroup>

<ChoiceGroup selectionMode="single" aria-label="Required example">
  <ChoiceIconButton value="left" tooltip="Left align" required>
    <Icon iconType="alignLeft" />
  </ChoiceIconButton>
  <ChoiceIconButton value="center" tooltip="Center">
    <Icon iconType="alignCenter" />
  </ChoiceIconButton>
  <ChoiceIconButton value="right" tooltip="Right align">
    <Icon iconType="alignRight" />
  </ChoiceIconButton>
</ChoiceGroup>

Multiple

Use required on a Choice subcomponent to indicate that this specific option must be selected, such as an agreement the user must accept.

<ChoiceGroup
  selectionMode="multiple"
  aria-label="Please verify the following before you continue."
  defaultSelectedValues={['reviewed', 'approved']}
>
  <ChoiceCard value="reviewed" required>
    I have reviewed my design
  </ChoiceCard>
  <ChoiceCard value="approved" required>
    I approve of my design
  </ChoiceCard>
  <ChoiceCard value="eaten">I have eaten breakfast today</ChoiceCard>
</ChoiceGroup>

<ChoiceGroup
  selectionMode="multiple"
  aria-label="Please verify the following before you continue."
  defaultSelectedValues={['reviewed', 'approved']}
>
  <ChoiceCard value="reviewed" required>
    I have reviewed my design
  </ChoiceCard>
  <ChoiceCard value="approved" required>
    I approve of my design
  </ChoiceCard>
  <ChoiceCard value="eaten">I have eaten breakfast today</ChoiceCard>
</ChoiceGroup>

Labels, errors, and helper text

Use the FormField components to add a label, error message, or helper text to a Choice Group. They apply the necessary ARIA attributes for you, so you don't need to add them yourself.

Managing State

Controlled

Single

selectedValue is the value of the currently selected Choice, or an empty string ('') if nothing is selected. onSelectedValueChange receives the newly selected value and the native change event. Update your state in the handler so the group reflects the new selection.

() => {
  const [shippingMethod, setShippingMethod] = React.useState('standard')

  return (
    <>
      <ChoiceGroup
        selectionMode="single"
        aria-label="Select a shipping method"
        selectedValue={shippingMethod}
        onSelectedValueChange={setShippingMethod}
      >
        <ChoiceCard value="standard">
          <FlexBox gap="between-icon-and-text">
            <Icon iconType="delivery" alt="" />
            <Box>
              Standard
              <Typography fontSkin="body-small">
                Arrives in 5-7 business days
              </Typography>
            </Box>
          </FlexBox>
        </ChoiceCard>
        <ChoiceCard value="express">
          <FlexBox gap="between-icon-and-text">
            <Icon iconType="deliveryFast" alt="" />
            <Box>
              Express
              <Typography fontSkin="body-small">
                Arrives in 3-5 business days
              </Typography>
            </Box>
          </FlexBox>
        </ChoiceCard>
      </ChoiceGroup>

      <Box fontSkin="footnote" textColor="subtle" mt="3">
        Selected method: {shippingMethod}
      </Box>
    </>
  )
}

() => {
  const [shippingMethod, setShippingMethod] = React.useState('standard')

  return (
    <>
      <ChoiceGroup
        selectionMode="single"
        aria-label="Select a shipping method"
        selectedValue={shippingMethod}
        onSelectedValueChange={setShippingMethod}
      >
        <ChoiceCard value="standard">
          <FlexBox gap="between-icon-and-text">
            <Icon iconType="delivery" alt="" />
            <Box>
              Standard
              <Typography fontSkin="body-small">
                Arrives in 5-7 business days
              </Typography>
            </Box>
          </FlexBox>
        </ChoiceCard>
        <ChoiceCard value="express">
          <FlexBox gap="between-icon-and-text">
            <Icon iconType="deliveryFast" alt="" />
            <Box>
              Express
              <Typography fontSkin="body-small">
                Arrives in 3-5 business days
              </Typography>
            </Box>
          </FlexBox>
        </ChoiceCard>
      </ChoiceGroup>

      <Box fontSkin="footnote" textColor="subtle" mt="3">
        Selected method: {shippingMethod}
      </Box>
    </>
  )
}

Multiple

selectedValues is an array of the values of the currently selected Choice components, or an empty array ([]) if nothing is selected. onSelectedValuesChange receives the updated array and the native change event. Update your state in the handler so the group reflects the new selection.

() => {
  const [filters, setFilters] = React.useState(['elegant', 'modern'])

  return (
    <>
      <ChoiceGroup
        selectionMode="multiple"
        aria-label="Filter by style"
        selectedValues={filters}
        onSelectedValuesChange={setFilters}
      >
        <ChoiceButton value="elegant">Elegant</ChoiceButton>
        <ChoiceButton value="modern">Modern</ChoiceButton>
        <ChoiceButton value="hideous">Hideous</ChoiceButton>
      </ChoiceGroup>

      <Box fontSkin="footnote" textColor="subtle" mt="3">
        Selected filters: {filters.join(', ')}
      </Box>
    </>
  )
}

() => {
  const [filters, setFilters] = React.useState(['elegant', 'modern'])

  return (
    <>
      <ChoiceGroup
        selectionMode="multiple"
        aria-label="Filter by style"
        selectedValues={filters}
        onSelectedValuesChange={setFilters}
      >
        <ChoiceButton value="elegant">Elegant</ChoiceButton>
        <ChoiceButton value="modern">Modern</ChoiceButton>
        <ChoiceButton value="hideous">Hideous</ChoiceButton>
      </ChoiceGroup>

      <Box fontSkin="footnote" textColor="subtle" mt="3">
        Selected filters: {filters.join(', ')}
      </Box>
    </>
  )
}

Uncontrolled

Omit selectedValue/selectedValues to allow the browser to manage the state. Optionally, use defaultSelectedValue/defaultSelectedValues to set the initially selected value(s), and/or pass onSelectedValueChange/onSelectedValuesChange to react to changes (for example, to track the selection) without taking over the state.

<ChoiceGroup
  aria-label="Filter by style"
  defaultSelectedValues={['ugly']}
  onSelectedValuesChange={value => trackSelection(value)}
>
  <ChoiceButton value="elegant">Elegant</ChoiceButton>
  <ChoiceButton value="modern">Modern</ChoiceButton>
  <ChoiceButton value="ugly">Ugly</ChoiceButton>
</ChoiceGroup>

<ChoiceGroup
  aria-label="Filter by style"
  defaultSelectedValues={['ugly']}
  onSelectedValuesChange={value => trackSelection(value)}
>
  <ChoiceButton value="elegant">Elegant</ChoiceButton>
  <ChoiceButton value="modern">Modern</ChoiceButton>
  <ChoiceButton value="ugly">Ugly</ChoiceButton>
</ChoiceGroup>

Accessibility

ChoiceGroup must have a localized accessible name.

Use a FormLabel to provide a visible and accessible name (recommended, see Labels, helpers, and error text). Alternatively, use custom ARIA labels (see Accessibility guidelines).

Layout and spacing

ChoiceGroup uses a sensible default layout for its subcomponents. To customize the layout, compose the options inside a FlexBox with gap between-controls, or a nested GridContainer.

() => {
  const ExampleChoiceCard = ({ value }) => (
    <ChoiceCard indicatorMode="floating" value={value} fullBleed>
      <Box bgc="promo" style={{ height: 100 }}></Box>
      <Box p={4}>
        <Typography fontSkin="title-item">Title</Typography>
        <Typography fontSkin="body-small">Description</Typography>
      </Box>
    </ChoiceCard>
  )

  return (
    <>
      <Box mb={3}>Default layout</Box>
      <ChoiceGroup selectionMode="multiple" aria-label="Default layout">
        <ExampleChoiceCard value="a" />
        <ExampleChoiceCard value="b" />
        <ExampleChoiceCard value="c" />
        <ExampleChoiceCard value="d" />
      </ChoiceGroup>

      <Box mt="between-subsections" mb={3}>
        Custom layout using FlexBox
      </Box>
      <ChoiceGroup selectionMode="multiple" aria-label="Custom layout">
        <FlexBox
          style={{ width: '100%' }}
          gap="between-controls"
          flexDirection="row"
          alignItems="stretch"
        >
          <ExampleChoiceCard value="a" />
          <ExampleChoiceCard value="b" />
          <ExampleChoiceCard value="c" />
          <ExampleChoiceCard value="d" />
        </FlexBox>
      </ChoiceGroup>

      <Box mt="between-subsections" mb={3}>
        Custom layout using Grid
      </Box>
      <ChoiceGroup selectionMode="multiple" aria-label="Custom layout">
        <GridContainer>
          <Row verticalGap="matchGutter">
            <Column span={6}>
              <ExampleChoiceCard value="a" />
            </Column>
            <Column span={6}>
              <ExampleChoiceCard value="b" />
            </Column>
            <Column span={6}>
              <ExampleChoiceCard value="c" />
            </Column>
            <Column span={6}>
              <ExampleChoiceCard value="d" />
            </Column>
          </Row>
        </GridContainer>
      </ChoiceGroup>
    </>
  )
}

() => {
  const ExampleChoiceCard = ({ value }) => (
    <ChoiceCard indicatorMode="floating" value={value} fullBleed>
      <Box bgc="promo" style={{ height: 100 }}></Box>
      <Box p={4}>
        <Typography fontSkin="title-item">Title</Typography>
        <Typography fontSkin="body-small">Description</Typography>
      </Box>
    </ChoiceCard>
  )

  return (
    <>
      <Box mb={3}>Default layout</Box>
      <ChoiceGroup selectionMode="multiple" aria-label="Default layout">
        <ExampleChoiceCard value="a" />
        <ExampleChoiceCard value="b" />
        <ExampleChoiceCard value="c" />
        <ExampleChoiceCard value="d" />
      </ChoiceGroup>

      <Box mt="between-subsections" mb={3}>
        Custom layout using FlexBox
      </Box>
      <ChoiceGroup selectionMode="multiple" aria-label="Custom layout">
        <FlexBox
          style={{ width: '100%' }}
          gap="between-controls"
          flexDirection="row"
          alignItems="stretch"
        >
          <ExampleChoiceCard value="a" />
          <ExampleChoiceCard value="b" />
          <ExampleChoiceCard value="c" />
          <ExampleChoiceCard value="d" />
        </FlexBox>
      </ChoiceGroup>

      <Box mt="between-subsections" mb={3}>
        Custom layout using Grid
      </Box>
      <ChoiceGroup selectionMode="multiple" aria-label="Custom layout">
        <GridContainer>
          <Row verticalGap="matchGutter">
            <Column span={6}>
              <ExampleChoiceCard value="a" />
            </Column>
            <Column span={6}>
              <ExampleChoiceCard value="b" />
            </Column>
            <Column span={6}>
              <ExampleChoiceCard value="c" />
            </Column>
            <Column span={6}>
              <ExampleChoiceCard value="d" />
            </Column>
          </Row>
        </GridContainer>
      </ChoiceGroup>
    </>
  )
}

Subcomponents

ChoiceButton

Use ChoiceButton for compact choices that should feel like selectable buttons, such as sizes, quantities, or short text options.

<ChoiceGroup selectionMode="single" aria-label="Size">
  <ChoiceButton value="s">Small</ChoiceButton>
  <ChoiceButton value="m">Medium</ChoiceButton>
  <ChoiceButton value="l">Large</ChoiceButton>
</ChoiceGroup>

<ChoiceGroup selectionMode="single" aria-label="Size">
  <ChoiceButton value="s">Small</ChoiceButton>
  <ChoiceButton value="m">Medium</ChoiceButton>
  <ChoiceButton value="l">Large</ChoiceButton>
</ChoiceGroup>

ChoiceIconButton

Use ChoiceIconButton for icon-only choices that are universally understood actions such as delete, download, and edit.

<ChoiceGroup selectionMode="single" aria-label="Choose an action">
  <ChoiceIconButton value="delete" tooltip="Delete">
    <Icon iconType="delete" alt="" />
  </ChoiceIconButton>
  <ChoiceIconButton value="duplicate" tooltip="Duplicate">
    <Icon iconType="download" alt="" />
  </ChoiceIconButton>
  <ChoiceIconButton value="edit" tooltip="Edit">
    <Icon iconType="edit" alt="" />
  </ChoiceIconButton>
</ChoiceGroup>

<ChoiceGroup selectionMode="single" aria-label="Choose an action">
  <ChoiceIconButton value="delete" tooltip="Delete">
    <Icon iconType="delete" alt="" />
  </ChoiceIconButton>
  <ChoiceIconButton value="duplicate" tooltip="Duplicate">
    <Icon iconType="download" alt="" />
  </ChoiceIconButton>
  <ChoiceIconButton value="edit" tooltip="Edit">
    <Icon iconType="edit" alt="" />
  </ChoiceIconButton>
</ChoiceGroup>

Refer to IconButton tooltip for usage guidelines.

ChoiceCard

Use ChoiceCard for richer selectable content.

<ChoiceGroup
  selectionMode="single"
  aria-label="Select a shipping method"
  defaultSelectedValue="standard"
>
  <ChoiceCard value="standard">
    <FlexBox gap="between-icon-and-text">
      <Icon iconType="delivery" alt="" />
      <Box>
        Standard
        <Typography fontSkin="body-small">
          Arrives in 5-7 business days
        </Typography>
      </Box>
    </FlexBox>
  </ChoiceCard>
  <ChoiceCard value="express">
    <FlexBox gap="between-icon-and-text">
      <Icon iconType="deliveryFast" alt="" />
      <Box>
        Express
        <Typography fontSkin="body-small">
          Arrives in 3-5 business days
        </Typography>
      </Box>
    </FlexBox>
  </ChoiceCard>
</ChoiceGroup>

<ChoiceGroup
  selectionMode="single"
  aria-label="Select a shipping method"
  defaultSelectedValue="standard"
>
  <ChoiceCard value="standard">
    <FlexBox gap="between-icon-and-text">
      <Icon iconType="delivery" alt="" />
      <Box>
        Standard
        <Typography fontSkin="body-small">
          Arrives in 5-7 business days
        </Typography>
      </Box>
    </FlexBox>
  </ChoiceCard>
  <ChoiceCard value="express">
    <FlexBox gap="between-icon-and-text">
      <Icon iconType="deliveryFast" alt="" />
      <Box>
        Express
        <Typography fontSkin="body-small">
          Arrives in 3-5 business days
        </Typography>
      </Box>
    </FlexBox>
  </ChoiceCard>
</ChoiceGroup>

Indicator

Use indicatorMode and indicatorPosition to customize the visibility and location of the radio or checkbox indicator.

() => {
  const cardIndicatorPositions = [
    'top-left',
    'top-right',
    'center-left',
    'center-right',
  ]
  const cardIndicatorModes = ['inline', 'floating'] // also 'none'

  return (
    <ChoiceGroup
      selectionMode="single"
      aria-label={`Choose a card indicator position`}
    >
      {cardIndicatorModes.map(indicatorMode => (
        <>
          {cardIndicatorPositions.map(indicatorPosition => (
            <ChoiceCard
              indicatorMode={indicatorMode}
              indicatorPosition={indicatorPosition}
              key={`${indicatorMode}-${indicatorPosition}`}
              value={`${indicatorMode}-${indicatorPosition}`}
              aria-label={`${indicatorMode}-${indicatorPosition}`}
            >
              <Typography fontSkin="title-item">{indicatorPosition}</Typography>
              <Typography fontSkin="title-item">{indicatorMode}</Typography>
            </ChoiceCard>
          ))}
        </>
      ))}
      <ChoiceCard indicatorMode="none" value="none" aria-label="none">
        <Typography fontSkin="title-item">none</Typography>
      </ChoiceCard>
    </ChoiceGroup>
  )
}

() => {
  const cardIndicatorPositions = [
    'top-left',
    'top-right',
    'center-left',
    'center-right',
  ]
  const cardIndicatorModes = ['inline', 'floating'] // also 'none'

  return (
    <ChoiceGroup
      selectionMode="single"
      aria-label={`Choose a card indicator position`}
    >
      {cardIndicatorModes.map(indicatorMode => (
        <>
          {cardIndicatorPositions.map(indicatorPosition => (
            <ChoiceCard
              indicatorMode={indicatorMode}
              indicatorPosition={indicatorPosition}
              key={`${indicatorMode}-${indicatorPosition}`}
              value={`${indicatorMode}-${indicatorPosition}`}
              aria-label={`${indicatorMode}-${indicatorPosition}`}
            >
              <Typography fontSkin="title-item">{indicatorPosition}</Typography>
              <Typography fontSkin="title-item">{indicatorMode}</Typography>
            </ChoiceCard>
          ))}
        </>
      ))}
      <ChoiceCard indicatorMode="none" value="none" aria-label="none">
        <Typography fontSkin="title-item">none</Typography>
      </ChoiceCard>
    </ChoiceGroup>
  )
}

Full Bleed

Use fullBleed to expand the content to the edges of the card.

<ChoiceGroup selectionMode="single" aria-label="Select a fullBleed option">
  <FlexBox gap="between-controls">
    <ChoiceCard value="full-bleed-1" fullBleed indicatorMode="floating">
      <Box bgc="promo" style={{ height: '200px' }} />
      <Box>
        <Typography fontSkin="title-item">Full bleed</Typography>
        <Typography fontSkin="body-small">With floating indicator</Typography>
      </Box>
    </ChoiceCard>
    <ChoiceCard value="full-bleed-2" fullBleed indicatorMode="floating">
      <Box bgc="promo" style={{ height: '200px' }} />
      <Box p={4}>
        <Typography fontSkin="title-item">Full bleed</Typography>
        <Typography fontSkin="body-small">
          With floating indicator and padded contents
        </Typography>
      </Box>
    </ChoiceCard>
    <ChoiceCard value="full-bleed-3" fullBleed indicatorMode="inline">
      <FlexBox justifyContent="space-between">
        <Box p={4}>
          <Typography fontSkin="title-item">Full bleed</Typography>
          <Typography fontSkin="body-small">
            With inline indicator and padded contents
          </Typography>
        </Box>
        <Box bgc="promo" style={{ height: '200px', width: '200px' }} />
      </FlexBox>
    </ChoiceCard>
    <ChoiceCard
      value="full-bleed-4"
      fullBleed
      indicatorMode="inline"
      indicatorPosition="top-right"
    >
      <FlexBox justifyContent="space-between">
        <Box bgc="promo" style={{ height: '200px', width: '200px' }} />
        <Box p={4}>
          <Typography fontSkin="title-item">Full bleed</Typography>
          <Typography fontSkin="body-small">
            With inline indicator and padded contents
          </Typography>
        </Box>
      </FlexBox>
    </ChoiceCard>
  </FlexBox>
</ChoiceGroup>

<ChoiceGroup selectionMode="single" aria-label="Select a fullBleed option">
  <FlexBox gap="between-controls">
    <ChoiceCard value="full-bleed-1" fullBleed indicatorMode="floating">
      <Box bgc="promo" style={{ height: '200px' }} />
      <Box>
        <Typography fontSkin="title-item">Full bleed</Typography>
        <Typography fontSkin="body-small">With floating indicator</Typography>
      </Box>
    </ChoiceCard>
    <ChoiceCard value="full-bleed-2" fullBleed indicatorMode="floating">
      <Box bgc="promo" style={{ height: '200px' }} />
      <Box p={4}>
        <Typography fontSkin="title-item">Full bleed</Typography>
        <Typography fontSkin="body-small">
          With floating indicator and padded contents
        </Typography>
      </Box>
    </ChoiceCard>
    <ChoiceCard value="full-bleed-3" fullBleed indicatorMode="inline">
      <FlexBox justifyContent="space-between">
        <Box p={4}>
          <Typography fontSkin="title-item">Full bleed</Typography>
          <Typography fontSkin="body-small">
            With inline indicator and padded contents
          </Typography>
        </Box>
        <Box bgc="promo" style={{ height: '200px', width: '200px' }} />
      </FlexBox>
    </ChoiceCard>
    <ChoiceCard
      value="full-bleed-4"
      fullBleed
      indicatorMode="inline"
      indicatorPosition="top-right"
    >
      <FlexBox justifyContent="space-between">
        <Box bgc="promo" style={{ height: '200px', width: '200px' }} />
        <Box p={4}>
          <Typography fontSkin="title-item">Full bleed</Typography>
          <Typography fontSkin="body-small">
            With inline indicator and padded contents
          </Typography>
        </Box>
      </FlexBox>
    </ChoiceCard>
  </FlexBox>
</ChoiceGroup>

Even Height

<ChoiceGroup selectionMode="multiple" aria-label="Choose a card (even height)">
  <FlexBox flexDirection="row" gap="between-controls" style={{ width: '100%' }}>
    <ChoiceCard key="short" value="short" evenHeight>
      <FlexBox flexDirection="column" gap={2}>
        <Typography fontSkin="title-item">Short title</Typography>
        <Typography fontSkin="body-small">Short description</Typography>
      </FlexBox>
    </ChoiceCard>
    <ChoiceCard key="medium" value="medium" evenHeight>
      <FlexBox flexDirection="column" gap={2}>
        <Typography fontSkin="title-item">Medium title</Typography>
        <Typography fontSkin="body-small">Medium description line 1</Typography>
        <Typography fontSkin="body-small">Medium description line 2</Typography>
      </FlexBox>
    </ChoiceCard>
    <ChoiceCard key="long" value="long" evenHeight>
      <FlexBox flexDirection="column" gap={2}>
        <Typography fontSkin="title-item">Long title</Typography>
        <Typography fontSkin="body-small">Long description line 1</Typography>
        <Typography fontSkin="body-small">Long description line 2</Typography>
        <Typography fontSkin="body-small">Long description line 3</Typography>
      </FlexBox>
    </ChoiceCard>
  </FlexBox>
</ChoiceGroup>

<ChoiceGroup selectionMode="multiple" aria-label="Choose a card (even height)">
  <FlexBox flexDirection="row" gap="between-controls" style={{ width: '100%' }}>
    <ChoiceCard key="short" value="short" evenHeight>
      <FlexBox flexDirection="column" gap={2}>
        <Typography fontSkin="title-item">Short title</Typography>
        <Typography fontSkin="body-small">Short description</Typography>
      </FlexBox>
    </ChoiceCard>
    <ChoiceCard key="medium" value="medium" evenHeight>
      <FlexBox flexDirection="column" gap={2}>
        <Typography fontSkin="title-item">Medium title</Typography>
        <Typography fontSkin="body-small">Medium description line 1</Typography>
        <Typography fontSkin="body-small">Medium description line 2</Typography>
      </FlexBox>
    </ChoiceCard>
    <ChoiceCard key="long" value="long" evenHeight>
      <FlexBox flexDirection="column" gap={2}>
        <Typography fontSkin="title-item">Long title</Typography>
        <Typography fontSkin="body-small">Long description line 1</Typography>
        <Typography fontSkin="body-small">Long description line 2</Typography>
        <Typography fontSkin="body-small">Long description line 3</Typography>
      </FlexBox>
    </ChoiceCard>
  </FlexBox>
</ChoiceGroup>

ChoiceTile

Use ChoiceTile to make supported SWAN tile components selectable while preserving tile-specific selected styling. Supported tile components are currently FileTile and components built using BaseTile (e.g. TemplateTile). Do not use ChoiceTile as a general-purpose wrapper for custom content.

<FlexBox flexDirection="column" gap="between-controls">
  <ChoiceGroup selectionMode="multiple" aria-label="Choose BaseTile examples">
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="standard"
        aria-label="Standard"
      >
        <BaseTile skin="standard">
          <BaseTileBody>
            <BaseTileName>Standard</BaseTileName>
            <Typography>This is a standard BaseTile.</Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="card"
        aria-label="Card"
      >
        <BaseTile skin="card">
          <BaseTileBody>
            <BaseTileName>Card</BaseTileName>
            <Typography>This is a card BaseTile.</Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1-2.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="card-full-bleed-covering"
        aria-label="Card full bleed, covering"
      >
        <BaseTile skin="card-full-bleed">
          <BaseTileBody>
            <BaseTileName>
              <BaseTileTargetCovering>
                <Link href="#">Full bleed card</Link>
              </BaseTileTargetCovering>
            </BaseTileName>
            <Typography fontSkin="body-small" textColor="subtle">
              This example uses BaseTileCovering. Click the indicator to select
              it, click the tile itself to activate the covering link.
            </Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1-3.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
  <ChoiceGroup selectionMode="multiple" aria-label={`Choose FileTile examples`}>
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="thumb"
      >
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="thumb-no-delete"
      >
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="list"
      >
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="list-no-delete"
      >
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
        </FileTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
</FlexBox>

<FlexBox flexDirection="column" gap="between-controls">
  <ChoiceGroup selectionMode="multiple" aria-label="Choose BaseTile examples">
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="standard"
        aria-label="Standard"
      >
        <BaseTile skin="standard">
          <BaseTileBody>
            <BaseTileName>Standard</BaseTileName>
            <Typography>This is a standard BaseTile.</Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="card"
        aria-label="Card"
      >
        <BaseTile skin="card">
          <BaseTileBody>
            <BaseTileName>Card</BaseTileName>
            <Typography>This is a card BaseTile.</Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1-2.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="card-full-bleed-covering"
        aria-label="Card full bleed, covering"
      >
        <BaseTile skin="card-full-bleed">
          <BaseTileBody>
            <BaseTileName>
              <BaseTileTargetCovering>
                <Link href="#">Full bleed card</Link>
              </BaseTileTargetCovering>
            </BaseTileName>
            <Typography fontSkin="body-small" textColor="subtle">
              This example uses BaseTileCovering. Click the indicator to select
              it, click the tile itself to activate the covering link.
            </Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1-3.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
  <ChoiceGroup selectionMode="multiple" aria-label={`Choose FileTile examples`}>
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="thumb"
      >
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="thumb-no-delete"
      >
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="list"
      >
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="list-no-delete"
      >
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
        </FileTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
</FlexBox>

Indicator

Use indicatorMode and indicatorPosition to customize the visibility and location of the radio or checkbox indicator.

<FlexBox flexDirection="column" gap="between-controls">
  <ChoiceGroup
    selectionMode="multiple"
    aria-label="Choose a card indicator position"
  >
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="floating-top-left"
        aria-label="Floating, top-left"
      >
        <BaseTile skin="card">
          <BaseTileBody>
            <BaseTileName>
              <BaseTileTargetCovering>
                <Link href="#">Base Tile Name</Link>
              </BaseTileTargetCovering>
            </BaseTileName>
            <Typography>
              Deserunt veniam fugiat voluptate cupidatat sint.
            </Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-right"
        value="floating-top-right"
        aria-label="Floating, top-right"
      >
        <BaseTile skin="card">
          <BaseTileBody>
            <BaseTileName>
              <BaseTileTargetCovering>
                <Link href="#">Base Tile Name</Link>
              </BaseTileTargetCovering>
            </BaseTileName>
            <Typography>
              Deserunt veniam fugiat voluptate cupidatat sint.
            </Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1-2.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
      <ChoiceTile indicatorMode="none" value="none" aria-label="None">
        <BaseTile skin="card">
          <BaseTileBody>
            <BaseTileName>
              <BaseTileTargetCovering>
                <Link href="#">Base Tile Name</Link>
              </BaseTileTargetCovering>
            </BaseTileName>
            <Typography>
              Deserunt veniam fugiat voluptate cupidatat sint.
            </Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1-3.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
  <ChoiceGroup
    selectionMode="multiple"
    aria-label={`Choose a card indicator position`}
  >
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="thumb-top-left"
      >
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-right"
        value="thumb-top-right"
      >
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile indicatorMode="none" value="thumb-none">
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
  <ChoiceGroup
    selectionMode="multiple"
    aria-label={`Choose a card indicator position`}
  >
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="list-top-left"
      >
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-right"
        value="list-top-right"
      >
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile indicatorMode="none" value="list-none">
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
</FlexBox>

<FlexBox flexDirection="column" gap="between-controls">
  <ChoiceGroup
    selectionMode="multiple"
    aria-label="Choose a card indicator position"
  >
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="floating-top-left"
        aria-label="Floating, top-left"
      >
        <BaseTile skin="card">
          <BaseTileBody>
            <BaseTileName>
              <BaseTileTargetCovering>
                <Link href="#">Base Tile Name</Link>
              </BaseTileTargetCovering>
            </BaseTileName>
            <Typography>
              Deserunt veniam fugiat voluptate cupidatat sint.
            </Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-right"
        value="floating-top-right"
        aria-label="Floating, top-right"
      >
        <BaseTile skin="card">
          <BaseTileBody>
            <BaseTileName>
              <BaseTileTargetCovering>
                <Link href="#">Base Tile Name</Link>
              </BaseTileTargetCovering>
            </BaseTileName>
            <Typography>
              Deserunt veniam fugiat voluptate cupidatat sint.
            </Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1-2.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
      <ChoiceTile indicatorMode="none" value="none" aria-label="None">
        <BaseTile skin="card">
          <BaseTileBody>
            <BaseTileName>
              <BaseTileTargetCovering>
                <Link href="#">Base Tile Name</Link>
              </BaseTileTargetCovering>
            </BaseTileName>
            <Typography>
              Deserunt veniam fugiat voluptate cupidatat sint.
            </Typography>
          </BaseTileBody>
          <BaseTileHeader>
            <BaseTileImage alt="" src="/example-images/1x1-3.webp" />
          </BaseTileHeader>
        </BaseTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
  <ChoiceGroup
    selectionMode="multiple"
    aria-label={`Choose a card indicator position`}
  >
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="thumb-top-left"
      >
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-right"
        value="thumb-top-right"
      >
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile indicatorMode="none" value="thumb-none">
        <FileTile fileName="my-file.png" fileDescription="3.56 MB">
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
  <ChoiceGroup
    selectionMode="multiple"
    aria-label={`Choose a card indicator position`}
  >
    <FlexBox style={{ width: '100%' }} gap="between-controls">
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-left"
        value="list-top-left"
      >
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile
        indicatorMode="floating"
        indicatorPosition="top-right"
        value="list-top-right"
      >
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
      <ChoiceTile indicatorMode="none" value="list-none">
        <FileTile
          layout="list"
          fileName="my-file.png"
          fileDescription="3.56 MB"
        >
          <FileTileThumbnail />
          <FileTileDeleteButton />
        </FileTile>
      </ChoiceTile>
    </FlexBox>
  </ChoiceGroup>
</FlexBox>

ChoiceColorSwatch

Use ChoiceColorSwatch inside ColorSwatches when the selectable value is represented by a color swatch. ChoiceColorSwatch takes the same props as ColorSwatch.

<ChoiceGroup
  selectionMode="multiple"
  aria-label="Choose colors (multiple)"
  defaultSelectedValues={['red']}
>
  <ColorSwatches>
    <ChoiceColorSwatch value="red" primaryColor="red" accessibleText="Red" />
    <ChoiceColorSwatch
      value="indigo"
      primaryColor="indigo"
      accessibleText="Indigo"
    />
    <ChoiceColorSwatch
      value="green"
      primaryColor="green"
      accessibleText="Green"
      disabled
    />
  </ColorSwatches>
</ChoiceGroup>

<ChoiceGroup
  selectionMode="multiple"
  aria-label="Choose colors (multiple)"
  defaultSelectedValues={['red']}
>
  <ColorSwatches>
    <ChoiceColorSwatch value="red" primaryColor="red" accessibleText="Red" />
    <ChoiceColorSwatch
      value="indigo"
      primaryColor="indigo"
      accessibleText="Indigo"
    />
    <ChoiceColorSwatch
      value="green"
      primaryColor="green"
      accessibleText="Green"
      disabled
    />
  </ColorSwatches>
</ChoiceGroup>

Use Choice Group...

Don't use Choice Group...

Selection Mode

Single

Multiple

Disabled

Required

Single

Multiple

Labels, errors, and helper text

Managing State

Controlled

Single

Multiple

Uncontrolled

Accessibility

Layout and spacing

Subcomponents

ChoiceButton

ChoiceIconButton

Tooltip

ChoiceCard

Indicator

Full Bleed

Even Height

ChoiceTile

Indicator

ChoiceColorSwatch

Related