ToggleGroup

The ToggleGroup component manages a set of related toggles with coordinated selection state. It supports both single-select (like a radio group) and multi-select modes. Built on top of the Toggle component with shared variant and size context via React Context.

Preview

Installation

npx novaui-cli add toggle-group

Import

import { ToggleGroup, ToggleGroupItem } from 'novaui-components'

Basic Usage

A single-select toggle group where only one item can be active:

import { useState } from 'react'
import { ToggleGroup, ToggleGroupItem } from 'novaui-components'

export function BasicToggleGroup() {
  const [value, setValue] = useState('left')

  return (
    <ToggleGroup type="single" value={value} onValueChange={setValue}>
      <ToggleGroupItem value="left">Left</ToggleGroupItem>
      <ToggleGroupItem value="center">Center</ToggleGroupItem>
      <ToggleGroupItem value="right">Right</ToggleGroupItem>
    </ToggleGroup>
  )
}

Selection Types

Single Selection

Only one item can be active at a time. Selecting a new item deselects the previous one:

<ToggleGroup type="single" value="list" onValueChange={setValue}>
  <ToggleGroupItem value="grid">Grid</ToggleGroupItem>
  <ToggleGroupItem value="list">List</ToggleGroupItem>
  <ToggleGroupItem value="table">Table</ToggleGroupItem>
</ToggleGroup>

Multiple Selection

Multiple items can be active simultaneously:

import { useState } from 'react'
import { ToggleGroup, ToggleGroupItem } from 'novaui-components'

export function MultipleToggleGroup() {
  const [values, setValues] = useState(['bold', 'italic'])

  return (
    <ToggleGroup type="multiple" value={values} onValueChange={setValues}>
      <ToggleGroupItem value="bold">B</ToggleGroupItem>
      <ToggleGroupItem value="italic">I</ToggleGroupItem>
      <ToggleGroupItem value="underline">U</ToggleGroupItem>
    </ToggleGroup>
  )
}

Variants

Outline

<ToggleGroup type="single" variant="outline" value="day" onValueChange={setValue}>
  <ToggleGroupItem value="day">Day</ToggleGroupItem>
  <ToggleGroupItem value="week">Week</ToggleGroupItem>
  <ToggleGroupItem value="month">Month</ToggleGroupItem>
</ToggleGroup>

Sizes

Small

<ToggleGroup type="single" size="sm" value="s" onValueChange={setValue}>
  <ToggleGroupItem value="s">S</ToggleGroupItem>
  <ToggleGroupItem value="m">M</ToggleGroupItem>
  <ToggleGroupItem value="l">L</ToggleGroupItem>
</ToggleGroup>

Large

<ToggleGroup type="single" size="lg" value="a" onValueChange={setValue}>
  <ToggleGroupItem value="a">Option A</ToggleGroupItem>
  <ToggleGroupItem value="b">Option B</ToggleGroupItem>
</ToggleGroup>

Props API

ToggleGroupProps

Extends React.ComponentPropsWithoutRef<typeof View> and VariantProps<typeof toggleVariants>:

Prop	Type	Default	Description
`type`	`'single' \| 'multiple'`	required	Whether one or many items can be active
`value`	`string \| string[]`	-	The currently active value(s)
`onValueChange`	`(value: string \| string[]) => void`	-	Callback fired when the selection changes
`variant`	`'default' \| 'outline'`	`'default'`	Visual style variant applied to all items
`size`	`'default' \| 'sm' \| 'lg'`	`'default'`	Size applied to all items
`className`	`string`	-	Additional CSS classes for the group container

ToggleGroupItemProps

Extends React.ComponentPropsWithoutRef<typeof Toggle>:

Prop	Type	Default	Description
`value`	`string`	required	The value this item represents
`className`	`string`	-	Additional CSS classes
`children`	`React.ReactNode`	-	Item content (text or icon)

Best Practices

Choose the right type: Use single for mutually exclusive options (view modes) and multiple for combinable options (text formatting)
Keep items concise: Toggle labels should be short — single words or icons work best
Consistent sizing: Use the group's size prop rather than sizing individual items
Default selection: For single type, always provide an initial value so one item is active

Use Toggle for standalone toggle buttons not part of a group
Use RadioGroup for single selection with radio button styling
Use ButtonGroup for grouped action buttons that are not toggleable

Continue reading

Getting Started Components Overview Popular: Dialog SEO Playbook

ToggleGroup

Continue reading

On this page