Toggle Group

The ToggleGroup component provides a set of toggle buttons that can be used to switch between different states or options. It is composed of subcomponents such as ToggleGroup.Root and ToggleGroup.Item to offer a structured and customizable interface.

Usage

import { ToggleGroup } from '@harnessio/ui/components'

// ...

return (
  <ToggleGroup.Root
    type="multiple"
    value={['2']}
    orientation="vertical"
    variant="outline-secondary"
    onValueChange={() => {}}
>
    <ToggleGroup.Item
        value="1"
        text="Option 1"
        tooltipProps={{
            title: 'Title',
            content: <p>This is a tooltip</p>
        }}
    />
    <ToggleGroup.Item value="2" text="Option 2" />
    <ToggleGroup.Item value="3" text="Option 3" />
  </ToggleGroup.Root>
)

Anatomy

All parts of the ToggleGroup component can be imported and composed as required.

<ToggleGroup.Root>
  <ToggleGroup.Item />
</ToggleGroup.Root>

Controlled and Uncontrolled Usage

The ToggleGroup.Root component can be used as a controlled or uncontrolled component.

• Controlled: Pass both the value prop and the onValueChange handler to fully control the selected value from outside the component.
• Uncontrolled with default value: Pass the value prop to set an initial selection. The component will manage its own state internally.
• Fully uncontrolled: Do not pass value. The component will manage its state entirely on its own.

Types

The ToggleGroup.Root component accepts a type prop to define selection behavior. Supported values are: single and multiple.

Variants

The ToggleGroup.Root component accepts a variant prop to control its appearance in active state. Supported values are: outline, ghost, and transparent. selectedVariant prop controls the style when the toggle is pressed, with options for primary and secondary.

Sizes

The ToggleGroup.Root component accepts a size prop to control its overall dimensions. Supported values are: default, sm, and xs.

Orientations

The ToggleGroup.Root component accepts a orientation prop to control the direction in which the items are laid out. Supported values are: horizontal and vertical.

Unselectable

The ToggleGroup.Root component accepts a unselectable prop to control whether the last selected item can be deselected. When set to true, the component prevents users from unselecting the last remaining active toggle.

Icon only

The ToggleGroup.Item component accepts a iconOnly prop. When this prop is set, the ToggleGroup.Item is styled to fit the dimensions of an icon, making it suitable for icon-only buttons. Note that when iconOnly is set, the text prop will be used for the area-label, and the prefixIcon prop will be used as the only icon displayed.

With tooltip

The ToggleGroup.Item component accepts a tooltipProps prop. When provided, the ToggleGroup.Item will be wrapped in a Tooltip component. The tooltipProps object can include the following properties from TooltipProps: title, content, side, and align.

API Reference

Root

The Root component serves as the main container for all toggle group elements.

Prop	Required	Default	Type
children	true		ReactNode
className	false		string
variant	false	outline	'outline' | 'ghost' | 'transparent'
selectedVariant	false	primary	'primary' | 'secondary'
type	false	single	'single' | 'multiple'
value	false		string | string[]
onChange	false		(value: string) => void | (value: string[]) => void
disabled	false	false	boolean
unselectable	false	false	boolean
orientation	false	horizontal	'horizontal' | 'vertical'
size	false	'md'	'md' | 'sm' | 'xs'

Item

The Item component is used to define each toggle button within the group.

Prop	Required	Default	Type
value	true		string
disabled	false	false	boolean
tooltipProps	false	undefined	Pick<TooltipProps, 'title' | 'content' | 'side' | 'align'>
text	false		string
iconOnly	false	false	boolean
prefixIcon	false		IconV2NamesType
prefixIconProps	false		IconPropsV2
suffixIcon	false		IconV2NamesType
suffixIconProps	false		IconPropsV2