@usevyre/react @usevyre/vue

Toggle Group

A segmented control for choosing one or many options. Controlled — onChange emits the value, not an event. Use type="single" (string) or type="multiple" (array). Not a Switch (boolean) or ButtonGroup (layout only).

Single & multiple

The first group is single-select via options; the second is multi-select with composable ToggleItem children. Arrow keys move focus between items.

Single — view (grid)

Multiple — format (bold)

import { useState } from "react";
import { ToggleGroup, ToggleItem, Stack, Text } from "@usevyre/react";

const [view, setView] = useState<string | null>("grid");
const [fmt, setFmt] = useState<string[]>(["bold"]);

<Stack direction="column" gap="lg">
  <Stack direction="column" gap="xs">
    <Text size="sm" color="muted">Single — view ({view ?? "none"})</Text>
    <ToggleGroup
      value={view}
      onChange={setView}
      options={[
        { value: "grid", label: "Grid" },
        { value: "list", label: "List" },
        { value: "board", label: "Board" },
      ]}
    />
  </Stack>
  <Stack direction="column" gap="xs">
    <Text size="sm" color="muted">Multiple — format ({fmt.join(", ") || "none"})</Text>
    <ToggleGroup type="multiple" value={fmt} onChange={setFmt}>
      <ToggleItem value="bold">B</ToggleItem>
      <ToggleItem value="italic">I</ToggleItem>
      <ToggleItem value="underline">U</ToggleItem>
    </ToggleGroup>
  </Stack>
</Stack>

<script setup>
import { ref } from "vue";
import { ToggleGroup, ToggleItem, Stack, Text } from "@usevyre/vue";

const view = ref("grid");
const fmt = ref(["bold"]);
</script>
<template>
  <Stack direction="column" gap="lg">
    <Stack direction="column" gap="xs">
      <Text size="sm" color="muted">Single — view ({{ view ?? "none" }})</Text>
      <ToggleGroup
        v-model="view"
        :options="[
          { value: 'grid', label: 'Grid' },
          { value: 'list', label: 'List' },
          { value: 'board', label: 'Board' },
        ]"
      />
    </Stack>
    <Stack direction="column" gap="xs">
      <Text size="sm" color="muted">Multiple — format ({{ fmt.join(', ') || 'none' }})</Text>
      <ToggleGroup type="multiple" v-model="fmt">
        <ToggleItem value="bold">B</ToggleItem>
        <ToggleItem value="italic">I</ToggleItem>
        <ToggleItem value="underline">U</ToggleItem>
      </ToggleGroup>
    </Stack>
  </Stack>
</template>

Props

Prop	Type	Default	Description
`type`	`"single" \| "multiple"`	`"single"`	single → value string\|null; multiple → value string[].
`value`	`string \| null \| string[]`	`—`	Controlled selected value (shape depends on type).
`onChange`	`(value) => void`	`—`	Emits the value — string\|null or string[]. Not an event.
`options`	`{ value; label?; icon?; disabled? }[]`	`—`	Alternative to ToggleItem children for simple lists.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Control size.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Layout direction.
`disabled`	`boolean`	`false`	Disable the whole group.

ToggleItem props

Use ToggleItem children for custom content (icons, mixed markup). For plain lists, prefer options.

Props

Prop	Type	Default	Description
`value`	`string`	`—`	This item's value (required).
`icon`	`ReactNode`	`—`	Optional leading icon.
`disabled`	`boolean`	`false`	Disable just this item.

AI Context

Valid props

Prop	Values	Default
`type`	`"single"`\|`"multiple"`	`single`
`size`	`"sm"`\|`"md"`\|`"lg"`	`md`
`orientation`	`"horizontal"`\|`"vertical"`	`horizontal`
`disabled`	`true`\|`false`	`false`

Common AI mistakes

onChange={(e) => set(e.target.value)}→ onChange={(value) => set(value)} — string|null (single) or string[] (multiple)
Using ToggleGroup for a single on/off setting→ Use <Switch> for on/off; ToggleGroup is for choosing among options
type="multiple" with a string value→ value={['a','b']} and onChange receives string[]
<ToggleItem> outside <ToggleGroup>→ Always nest ToggleItem inside ToggleGroup (or use options)

Quick examples

Single-select view switcher (options)

const [view, setView] = useState<string | null>("grid");

<ToggleGroup
  value={view}
  onChange={setView}
  options={[
    { value: "grid", label: "Grid" },
    { value: "list", label: "List" },
  ]}
/>

Multiple-select formatting (composable)

const [fmt, setFmt] = useState<string[]>(["bold"]);

<ToggleGroup type="multiple" value={fmt} onChange={setFmt}>
  <ToggleItem value="bold">B</ToggleItem>
  <ToggleItem value="italic">I</ToggleItem>
  <ToggleItem value="underline">U</ToggleItem>
</ToggleGroup>

← Toast Tooltip →