Last modified: August 22, 2025
The ToggleGroup component renders a list of selectable options, either in radio button or checkbox form.
design-guide-toggle-group
  1. Group label: the text that displays above the group of checkboxes.
  2. Tooltip: on hover, displays additional information about the field.
  3. Unchecked checkbox: an unselected checkbox.
  4. Option label: the text that displays next to the checkbox.
  5. Option description: the text that displays below the option label to describe the option.
import { ToggleGroup } from '@hubspot/ui-extensions';

const options = [1, 2, 3, 4].map((n) => ({
  label: `Option ${n}`,
  value: `${n}`,
  initialIsChecked: n === 2,
  readonly: false,
  description: `This is option ${n}`,
}));

const Extension = () => {
  return (
    <ToggleGroup
      name="toggle-checkboxes"
      label="Toggle these things"
      error={false}
      options={options}
      tooltip="Here's a secret tip."
      validationMessage="Make sure you do the thing correctly."
      required={false}
      inline={false}
      toggleType="checkboxList"
      variant="default"
    />
  );
};
PropTypeDescription
nameStringThe input’s unique identifier.
labelStringThe text that displays above the toggles.
optionsArrayAn array of options to display in the group. Each object in the array contains:
  • label (string)
  • value (string)
  • initialIsChecked (boolean)
  • readonly (boolean)
  • description (string)
toggleType'radioButtonList' | 'checkboxList' (default)The type of toggle, whether checkboxes or radio buttons. Radio buttons only allow one option to be selected.
variant'default' (default) | 'small'The size of the toggle.
errorBooleanWhen set to true, validationMessage is displayed as an error message if provided. The input will also render its error state to let the user know there is an error. If left false, validationMessage is displayed as a success message.
valueStringThe value of the toggle group.
  • Accepts a string when toggleType is radioButtonList.
  • Accepts an array when toggleType is checkboxList.
requiredBooleanWhen set to true, displays a required indicator next to the toggle group. Default is false.
tooltipStringText that will appear in a tooltip next to the toggle group label.
validationMessageStringThe text to display if the input has an error.
inlineBooleanWhen set to true, stacks the options horizontally. Default is false.
readonlyBooleanWhen set to true, users will not be able to select the toggle. Default is false.
onChange(checked: boolean) => voidA function that is invoked when the toggle is clicked.

​
Variants

By default, the toggle group will render as a vertical list of checkboxes. Using the toggleType prop, you can set the options to display as checkboxes or radio buttons. You can also use the inline prop to stack options horizontally.

toggle-group-checklist-variant

toggleType=‘checkboxList’ (default)

toggle-group-radio-buttons

toggleType=‘radioButtonList’

toggle-group-inline

inline={true}

​
Usage examples

  • A radio button list to enable salespeople to select one of four sales packages for a new customer.
  • A checkbox list to enable customer support reps to select several options of swag to send to a delightful customer.

​
Guidelines

  • DO: use this component when the user has a small selection of items to choose from. For longer lists of options, consider using the Select component instead.
  • DO: keep label options concise when possible.
  • DON’T: use toggle groups to display long lists of options.