Skip to main content
Last modified: August 22, 2025
The Toggle component renders a boolean toggle switch that can be configured with sizing, label position, read-only, and more.
toggle-example
import { Toggle } from '@hubspot/ui-extensions';

const Extension = () => {
  return (
    <Toggle
      size="md"
      label="My toggle"
      labelDisplay="top"
      initialIsChecked={true}
    />
  );
};

​
Props

PropTypeDescription
nameStringThe input’s unique identifier.
labelStringThe text that displays above the input.
size'xs' |'sm' | 'md' (default)The size of the toggle. Only 'md' sized toggles can display text on the toggle (ON, OFF). All other sizes will hide checked/unchecked text.
labelDisplay'inline' (default) | 'top' | 'hidden'The display option for the toggle label.
checkedBooleanWhether the toggle is selected. Default is false.
initialIsCheckedBooleanWhen set to true, the toggle will be selected by default. Sets the default checked state when the component is uncontrolled.
textCheckedStringThe text that displays on the toggle when checked. Default is ON. Extra small and small toggles will not display any text.
textUncheckedStringThe text that displays on the toggle when not checked. Default is OFF. Extra small and small toggles will not display any text.
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

Using the labelDisplay and size props, you can customize toggle appearance.
  • labelDisplay: set to 'inline' or 'top' to configure the label position, or set to 'hidden' to hide the label.
toggledisplay-examples
  • size: by default, toggles are set to 'md'. Shrink the toggle size by setting this prop to 'xs' or 'sm'. Note that only medium toggles will display ON/OFF status text.
toggle-size-examples