Automattic Design System

Components

ToggleGroupControl

ToggleGroupControl is a form component that lets users choose options represented in horizontal segments. To render options for this control use ToggleGroupControlOption component.

This component is intended for selecting a single persistent value from a set of options, similar to a how a radio button group would work. If you simply want a toggle to switch between views, use a TabPanel instead.

Only use this control when you know for sure the labels of items inside won’t wrap. For items with longer labels, you can consider a SelectControl or a CustomSelectControl component instead.

import { __experimentalToggleGroupControl as ToggleGroupControl } from '@wordpress/components';

View on Storybook

View in Figma

View source on GitHub

PropsPermalink to this section

NameDefaultDescription
help

ReactNode

Additional description for the control.

Only use for meaningful description or instructions for the control. An element containing the description will be programmatically associated to the BaseControl by the means of an aria-describedby attribute.

__nextHasNoMarginBottom

boolean

Start opting into the new margin-free styles that will become the default in a future version.

label Required

string

Label for the control.

hideLabelFromVisionfalse

boolean

If true, the label will only be visible to screen readers.

isAdaptiveWidthfalse

boolean

Determines if segments should be rendered with equal widths.

isBlockfalse

boolean

Renders ToggleGroupControl as a (CSS) block element, spanning the entire width of the available space. This is the recommended style when the options are text-based and not icons.

isDeselectablefalse

boolean

Whether an option can be deselected by clicking it again.

onChange

(value: string | number | undefined) => void

Callback when a segment is selected.

value

string | number | undefined

The selected value.

children Required

ReactNode

The options to render in the ToggleGroupControl, using either the ToggleGroupControlOption or ToggleGroupControlOptionIcon components.

disabledfalse

boolean

Whether the control is disabled.

size

"default" | "__unstable-large"

The size variant of the control.

__next40pxDefaultSize

boolean

Start opting into the larger default height that will become the default size in a future version.

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] = useState< ToggleGroupControlProps[ 'value' ] >(
		props.value
	);

	return (
		<ToggleGroupControl
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

With TooltipPermalink to this section

A tooltip can be shown for each option by enabling the showTooltip prop. The aria-label will be used in the tooltip if provided. Otherwise, the label will be used.

const WithTooltip = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] = useState< ToggleGroupControlProps[ 'value' ] >(
		props.value
	);

	return (
		<ToggleGroupControl
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

With IconsPermalink to this section

The ToggleGroupControlOptionIcon component can be used for icon options. A label is required on each option for accessibility, which will be shown in a tooltip.

const WithIcons = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] = useState< ToggleGroupControlProps[ 'value' ] >(
		props.value
	);

	return (
		<ToggleGroupControl
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

DeselectablePermalink to this section

When the isDeselectable prop is true, the option can be deselected by clicking on it again.

const Deselectable = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] = useState< ToggleGroupControlProps[ 'value' ] >(
		props.value
	);

	return (
		<ToggleGroupControl
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};

DisabledPermalink to this section

When the disabled prop is true, the control is unselectable.

const Disabled = ( {
	onChange,
	...props
} ) => {
	const [ value, setValue ] = useState< ToggleGroupControlProps[ 'value' ] >(
		props.value
	);

	return (
		<ToggleGroupControl
			{ ...props }
			onChange={ ( ...changeArgs ) => {
				setValue( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
			value={ value }
		/>
	);
};