Component | Selection Set

styleKeysselectionSet

Develop

A single select Section Set acts as a set of radio buttons, and only one value may be selected at a time. In React, single select is the default behavior.

This behavior allows multiple options to be selected at the same time — the component acting as a set of checkboxes.

You can set a Selection Set to have default values:

In React, you can optionally pass a defaultSelectedValues prop on the SelectionSet to specify an initial state.
In vanilla JS, set the checked property on the appropriate selection-set-input elements.

<SelectionSet defaultSelectedValue="B" />
<input
  type="radio"
  class="selection-set-input"
  name="exampleRadio"
  value="B"
  checked
/>

By default, the Selection Set's labels are neutral containers, so you can render just about anything inside of them. That includes entire Standard Tiles!

The "buttons" skin uses text-only labels, and puts some standard padding around the text, to give the selections a button-like appearance.

<SelectionSet skin="buttons" />
<div class="selection-set selection-set-skin-buttons" role="radiogroup"></div>

The "buttons with images" skin works like the above, but includes a small image or icon above the text.

<SelectionSet skin="buttons-with-images" />
<div
  class="selection-set selection-set-skin-buttons-with-images"
  role="radiogroup"
></div>

Sometimes you just want a single checkbox or radio button with a label next to it. You can do that with the "simple column" option, which gives a standard radio-button/checkbox look.

You can use this for checkboxes, too :

<SelectionSet skin="simple-column" />
<div
  class="
    selection-set selection-set-skin-simple-column selection-set-show-inputs
  "
  role="radiogroup"
></div>

The "tiles-horizontal", "tiles-vertical", and "tiles-mini" skins present the selections as simple tiles, arranging the contents of each tile either horizontally or vertically.

Note that the images in these skins are wrapped in a <SelectionSetTileImageContainer> element, and the image must be a <FluidImage> component.

The "mini" skin is designed to be visually compact. Tiles using this skin must feature the product name; price and image are optional. No other information (e.g. a description) should go on these tiles.

To provide error messaging about a Selection Set, place a "Selection Set Error" component right after the Set. (Don't forget to add the necessary ARIA attributes to the inputs!)

If you want to control the state of SelectionSet you can make use of the selectedValue/selectedValues and onSelectedValueChange/onSelectedValuesChange props.

A single-select SelectionSet should use the selectedValue and onSelectedValueChange props in order to control the state.

onSelectedValueChange will be invoked with the new value as the first arg and the actual <input> event as the second arg in case you need it.

() => {
  const [selectedValue, setSelectedValue] = React.useState('B')
  return (
    <SelectionSet
      variant="single-select"
      selectedValue={selectedValue}
      onSelectedValueChange={newSelectedValue =>
        setSelectedValue(newSelectedValue)
      }
    >
      <SelectionSetInput value="A">
        <SelectionSetLabel>A</SelectionSetLabel>
      </SelectionSetInput>
      <SelectionSetInput value="B">
        <SelectionSetLabel>B</SelectionSetLabel>
      </SelectionSetInput>
      <SelectionSetInput value="C">
        <SelectionSetLabel>C</SelectionSetLabel>
      </SelectionSetInput>
    </SelectionSet>
  )
}

A multi-select SelectionSet should use the selectedValues and onSelectedValuesChange props in order to control the state.

selectedValues is an object { [value: string]: boolean } which represents which values are selected and which are not. If a value is omitted from the object, it will be considered unselected.

onSelectedValuesChange will be invoked with an updated object representing the selected values as the first arg and the actual <input> event as the second arg in case you need it.

() => {
  const [selectedValues, setSelectedValues] = React.useState({
    B: true,
    C: true,
  })
  return (
    <SelectionSet
      variant="multi-select"
      selectedValues={selectedValues}
      onSelectedValuesChange={newSelectedValues =>
        setSelectedValues(newSelectedValues)
      }
    >
      <SelectionSetInput value="A">
        <SelectionSetLabel>A</SelectionSetLabel>
      </SelectionSetInput>
      <SelectionSetInput value="B">
        <SelectionSetLabel>B</SelectionSetLabel>
      </SelectionSetInput>
      <SelectionSetInput value="C">
        <SelectionSetLabel>C</SelectionSetLabel>
      </SelectionSetInput>
    </SelectionSet>
  )
}

SelectionSet

Prop	Type	Default	Description
skin	"standard" \| "buttons" \| "buttons-with-images" \| "simple-column" \| "tiles-horizontal" \| "tiles-vertical" \| "tiles-mini"	"standard"	The visual style of the SelectionSet
variant	"single-select" \| "multi-select"		`single-select` means using radio buttons, which are mutually exclusive `multi-select` means using checkbox options, of which many can be selected at once
selectedValue	string
defaultSelectedValue	string
onSelectedValueChange	(selectedValue: string, event: ChangeEvent<HTMLInputElement>) => void
selectedValues	SelectedValues
defaultSelectedValues	SelectedValues
onSelectedValuesChange	(newSelectedValues: SelectedValues, event: ChangeEvent<HTMLInputElement>) => void		Callback fired when one of the selections' value changes It is passed the updated set of selectedValue

All other props are forwarded to the element specified in thecomponentprop(default: <div/>)

SelectionSetInput

SelectionSetInput has no props of its own

All props are forwarded to the element specified in thecomponentprop(default: <input/>)

SelectionSetLabel

SelectionSetLabel has no props of its own

All props are forwarded to the element specified in thecomponentprop(default: <label/>)

When using the "buttons with images" skin, the images should be no taller than 30 pixels.

You cannot place another form element (such as an <input> tag) inside a SelectionSetLabel or selection-set-label.
The outermost Selection Set element can be combined with a grid row element, if the selections that the user is choosing from are spread out among the columns inside that row. For instance, if you are presenting a row of Standard Tiles to choose from, the grid row can also act as the Selection Set.

The outermost element (SelectionSet in React, or class selection-set in vanilla JS) must have an accessible label, such as an aria-labelledby attribute whose value is the id of the element that acts as a title for the Selection Set. (Typically, that labelling element is a heading that sits right above the Selection Set.) If the Selection Set does not have a visible title, then the outermost element instead needs an aria-label attribute whose value is a descriptive title of the Selection Set; this text must be localized, as some browsers will read it to the user.
If there is more than one input in the Selection Set, that outermost element must also have a role attribute; the React component will take care of this for you. For the vanilla JS API, if the Selection Set is a set of radio buttons, it should have role="radiogroup"; if it is an Selection Set of checkboxes, it should have role="group".
If a checkbox or radio button is a required field before the user can submit the form, add the attribute aria-required="true" to the input element.
When a Selection Set has an error, each input should have aria-describedby and aria-errormessage attributes whose value is the id of the error message. The error message should not be a label tag with a for attribute pointing to the input.

Selection Set

Playground

Single Select

Multi-Select

Setting Defaults

using Standard Tiles

Using horizontal tiles:

Skins

"Buttons" skin

"Buttons with Images" skin

"Simple Column" skin

"Tiles" skins

Error Messaging

Managing State in React

Single Select

Multi Select

Components

SelectionSet

SelectionSetInput

SelectionSetLabel

Guidelines

Designer Guidelines

Developer Guidelines

Accessibility Guidelines