Skip to main content

​
Overview

Single toggle
Toggle group
Toggle is a pressable button that maintains a pressed/active state. Unlike Switch (which is for binary settings), Toggle is used for actions: formatting (bold/italic), view switching (grid/list), and filter activation.
Use ToggleGroup when toggles are related and should behave as a group — either "single" (radio-like) or "multiple" (checkbox-like). Use standalone Toggle for independent on/off states.

​
Installation

npm install @araf-ds/core

​
Usage

import { Toggle, ToggleGroup, ToggleGroupItem } from "@araf-ds/core"

export default function Example() {
  return (
    <ToggleGroup type="single" defaultValue="grid">
      <ToggleGroupItem value="grid" aria-label="Grid view">
        <GridIcon size={16} />
      </ToggleGroupItem>
      <ToggleGroupItem value="list" aria-label="List view">
        <ListIcon size={16} />
      </ToggleGroupItem>
    </ToggleGroup>
  )
}

​
Variants

​
Single Toggle (Icon Only)

Off → On
<Toggle aria-label="Toggle bold">
  <BoldIcon size={16} />
</Toggle>

​
With Label

Off → On
<Toggle>
  <GridIcon size={16} />
  Grid view
</Toggle>

​
Toggle Group — Single Select

One item can be active at a time (radio-like behavior). 
<ToggleGroup type="single" defaultValue="grid">
  <ToggleGroupItem value="grid" aria-label="Grid view">
    <GridIcon size={16} />
    Grid
  </ToggleGroupItem>
  <ToggleGroupItem value="list" aria-label="List view">
    <ListIcon size={16} />
    List
  </ToggleGroupItem>
  <ToggleGroupItem value="table" aria-label="Table view">
    <TableIcon size={16} />
    Table
  </ToggleGroupItem>
</ToggleGroup>

​
Toggle Group — Multi Select (Text Formatting)

Multiple items can be active simultaneously (checkbox-like behavior).
Bold + Underline active
<ToggleGroup type="multiple">
  <ToggleGroupItem value="bold" aria-label="Bold">
    <BoldIcon size={16} />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Italic">
    <ItalicIcon size={16} />
  </ToggleGroupItem>
  <ToggleGroupItem value="underline" aria-label="Underline">
    <UnderlineIcon size={16} />
  </ToggleGroupItem>
</ToggleGroup>

​
Outline Variant

<Toggle variant="outline">
  <FilterIcon size={16} />
  Filter
</Toggle>

​
Sizes

<Toggle size="sm">SM</Toggle>
<Toggle size="md">MD</Toggle>
<Toggle size="lg">LG</Toggle>

​
API Reference

​
Toggle

​
pressed
boolean
Controlled pressed state.
​
onPressedChange
(pressed: boolean) => void
Callback fired when pressed state changes.
​
defaultPressed
boolean
default:"false"
Uncontrolled default pressed state.
​
disabled
boolean
default:"false"
Disables the toggle.
​
variant
string
default:"default"
Visual style. Values: default · outline
​
size
string
default:"md"
Button size. Values: sm · md · lg
​
aria-label
string
Accessible label — required for icon-only toggles where the visible content doesn’t describe the action.

​
ToggleGroup

​
type
string
required
Selection mode. "single" allows one active item; "multiple" allows many.
​
value
string | string[]
Controlled value. String for single, array for multiple.
​
onValueChange
(value: string | string[]) => void
Callback fired when selection changes.
​
defaultValue
string | string[]
Uncontrolled default value.
​
size
string
default:"md"
Applies to all items in the group. Values: sm · md · lg

​
Accessibility

  • Toggle renders as a <button> with aria-pressed="true|false" reflecting the current state
  • Icon-only toggles must have aria-label describing the action (e.g. "Toggle bold", not "B")
  • ToggleGroup uses role="group" with aria-label describing the group
  • Keyboard: Space/Enter toggles the focused item; Arrow keys navigate within ToggleGroup
  • State changes are announced to screen readers via aria-pressed

​
Do’s & Don’ts

Do

  • Use ToggleGroup type="single" for mutually exclusive view modes (grid/list)
  • Use ToggleGroup type="multiple" for independently combinable states (bold + italic)
  • Always provide aria-label for icon-only toggles
  • Use Toggle for UI state (view mode, filter) and Switch for settings (on/off preferences)

Don't

  • Don’t use Toggle as a navigation element — use Tabs instead
  • Don’t use Toggle for binary settings that persist across sessions — use Switch
  • Don’t use Toggle for form submission — use a Button or Checkbox
  • Don’t put too many items in a ToggleGroup — limit to 4–5 maximum