Toggle Group

A set of toggle buttons for multi-select or single-select options.

CMSPayload CMS Integration

Toggle groups can be configured through CMS fields for view mode selectors, alignment options, or other multi-choice UI configurations.

CMS Demo

See how content editors configure toggle groups in a CMS:

Single selection

Multiple selection

Outline variant

Sizes

Controlled (single)

Selected: center

Controlled (multiple)

Selected: bold

Disabled

Toggle GroupA toggle group for view selection

Payload Block Example

// In your Payload CMS block config
export const ViewSettings = {
  slug: "view-settings",
  fields: [
    {
      name: "defaultView",
      type: "select",
      options: [
        { label: "Grid", value: "grid" },
        { label: "List", value: "list" },
        { label: "Table", value: "table" },
      ],
      defaultValue: "grid",
    },
  ],
}

Rendering the Block

import { ToggleGroup, ToggleGroupItem } from "@corew500/ui"
import { Grid, List, Table } from "lucide-react"

export function ViewToggle({ defaultView }) {
  return (
    <ToggleGroup defaultValue={[defaultView]}>
      <ToggleGroupItem value="grid" aria-label="Grid view">
        <Grid className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="list" aria-label="List view">
        <List className="size-4" />
      </ToggleGroupItem>
      <ToggleGroupItem value="table" aria-label="Table view">
        <Table className="size-4" />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

Installation

pnpm add @corew500/ui

Usage

import { ToggleGroup, ToggleGroupItem } from "@corew500/ui"

<ToggleGroup defaultValue={["center"]}>
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

Examples

Single Selection

By default, only one item can be selected at a time.

<ToggleGroup defaultValue={["center"]}>
  <ToggleGroupItem value="left">
    <AlignLeft className="size-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="center">
    <AlignCenter className="size-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="right">
    <AlignRight className="size-4" />
  </ToggleGroupItem>
</ToggleGroup>

Multiple Selection

Use the multiple prop to allow selecting multiple items.

<ToggleGroup multiple defaultValue={["bold"]}>
  <ToggleGroupItem value="bold">
    <Bold className="size-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic">
    <Italic className="size-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="underline">
    <Underline className="size-4" />
  </ToggleGroupItem>
</ToggleGroup>

Outline Variant

<ToggleGroup variant="outline" defaultValue={["a"]}>
  <ToggleGroupItem value="a">A</ToggleGroupItem>
  <ToggleGroupItem value="b">B</ToggleGroupItem>
  <ToggleGroupItem value="c">C</ToggleGroupItem>
</ToggleGroup>

Sizes

<ToggleGroup size="sm" defaultValue={["a"]}>...</ToggleGroup>
<ToggleGroup size="default" defaultValue={["a"]}>...</ToggleGroup>
<ToggleGroup size="lg" defaultValue={["a"]}>...</ToggleGroup>

Props

ToggleGroup

Prop	Type	Default	Description
`value`	readonly any[]	—	The open state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the controlled counterpart of `defaultValue`.
`defaultValue`	readonly any[]	—	The open state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the uncontrolled counterpart of `value`.
`onValueChange`	(groupValue: any[], eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void	—	Callback fired when the pressed states of the toggle group changes.
`disabled`	enum	`false`	Whether the toggle group should ignore user interaction.
`orientation`	enum	`horizontal`	—
`loopFocus`	enum	`true`	Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
`multiple`	enum	`false`	When `false` only one item in the group can be pressed. If any item in the group becomes pressed, the others will become unpressed. When `true` multiple items can be pressed.
`style`	enum	—	Style applied to the element, or a function that returns a style object based on the component’s state.
`className`	enum	—	CSS class applied to the element, or a function that returns a class based on the component’s state.
`render`	enum	—	Allows you to replace the component’s HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`variant`	enum	—	—
`size`	enum	—	—
`spacing`	number	`0`	—

ToggleGroupItem

Prop	Type	Default	Description
`pressed`	enum	—	Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`.
`defaultPressed`	enum	`false`	Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`.
`disabled`	enum	`false`	Whether the component should ignore user interaction.
`onPressedChange`	(pressed: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element; }) => void	—	Callback fired when the pressed state is changed.
`value`	string	—	A unique string that identifies the toggle when used inside a toggle group.
`nativeButton`	enum	`true`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (e.g. `<div>`).
`style`	enum	—	Style applied to the element, or a function that returns a style object based on the component’s state.
`className`	enum	—	CSS class applied to the element, or a function that returns a class based on the component’s state.
`render`	enum	—	Allows you to replace the component’s HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`variant`	enum	`default`	—
`size`	enum	`default`	—