Skip to content

Components

Toggle

A button that keeps its pressed state: formatting, column sets, and any on/off that is not a switch.

Examples

Pressed and unpressed

A pressed toggle keeps its surface and takes the inset well, so it reads as a switch that has been pushed rather than a tab that has been selected.

A group: multiple or single

Multiple keeps every item independent. Single is a radiogroup — one tab stop, arrow keys, aria-checked — which is a different contract from a sliding segmented control.

multiple

Any number of options may be on at once (column visibility, overlays, layers).

single

Exactly one option is on (aggregation, density, mode).

SegmentedControl is one value with a sliding indicator. ToggleGroup is a set of independent options. They look related and are not interchangeable: a segmented control that allowed two selections would be a lie about the state.

SegmentedControl

A toolbar

A toolbar is one tab stop. A screen-reader user should not have to press Tab eleven times to cross a formatting strip.

Usage

import { Toggle, ToggleGroup, ToggleGroupItem } from "@luc/ui";
<Toggle label="Bold" defaultPressed onPressedChange={applyBold}>
  <RiBold />
</Toggle>

`pressed` plus `onPressedChange` controls it; `defaultPressed` leaves the state to the component. A group item takes `value` instead, and the group takes `type`.

API

Read from the published TypeScript API, so a prop that is not listed here does not exist and a default that is listed is the one the compiler sees.

Exported symbols
ExportKindSignature
Toggle8 documented props({ className, variant, size, block, label, ...props }: ToggleProps) => import("@types/react").JSX.Element
ToggleGroup10 documented props({ className, ...props }: ToggleGroupProps) => import("@types/react").JSX.Element
ToggleGroupItem6 documented props({ className, variant, size, label, ...props }: ToggleGroupItemProps) => import("@types/react").JSX.Element
toggleVariantsexport(props?: ({ variant?: "outline" | "default" | "soft" | null | undefined; size?: "sm" | "md" | "lg" | null | undefined; block?: boolean | null | undefined; } & import("class-variance-authority/dist/ty…

Toggle props

Type: ToggleProps

Values the compiler reads from the declaration.

Toggle props
PropTypeDefaultNotes
asChild?inheritedboolean | undefined—
block?boolean | null | undefined—
defaultPressed?inheritedboolean | undefined—The state of the toggle when initially rendered. Use `defaultPressed` if you do not need to control the state of the toggle.
label?string | undefined—Required for an icon-only toggle; ignored when children carry text.
onPressedChange?inherited((pressed: boolean) => void) | undefined—The callback that fires when the state of the toggle changes.
pressed?inheritedboolean | undefined—The controlled state of the toggle.
size?"sm" | "md" | "lg" | null | undefined—
variant?"outline" | "default" | "soft" | null | undefined—

ToggleGroup props

Type: (RadixToggleGroup.ToggleGroupSingleProps | RadixToggleGroup.ToggleGroupMultipleProps) & RefAttributes<HTMLDivElement>

Values the compiler reads from the declaration.

ToggleGroup props
PropTypeDefaultNotes
asChild?inheritedboolean | undefined—
defaultValue?inheritedstring | string[] | undefined—The value of the item that is pressed when initially rendered. Use `defaultValue` if you do not need to control the state of a toggle group. The value of the items that are presse…
dir?inheritedDirection | undefined—
disabled?inheritedboolean | undefined—Whether the group is disabled from user interaction.
loop?inheritedboolean | undefined—
onValueChange?inherited((value: string) => void) | ((value: string[]) => void) | undefined—The callback that fires when the value of the toggle group changes. The callback that fires when the state of the toggle group changes.
orientation?inherited"horizontal" | "vertical" | undefined—
rovingFocus?inheritedboolean | undefined—Whether the group should maintain roving focus of its buttons.
typeinherited"single" | "multiple"—
value?inheritedstring | string[] | undefined—The controlled stateful value of the item that is pressed. The controlled stateful value of the items that are pressed.

ToggleGroupItem props

Type: ToggleGroupItemProps

Values the compiler reads from the declaration.

ToggleGroupItem props
PropTypeDefaultNotes
asChild?inheritedboolean | undefined—
block?boolean | null | undefined—
label?string | undefined—
size?"sm" | "md" | "lg" | null | undefined—
valueinheritedstring—A string value for the toggle group item. All items within a toggle group should use a unique value.
variant?"outline" | "default" | "soft" | null | undefined—

Guidelines

Do

  • Use a `Toggle` for an action that applies immediately to what the reader is looking at, and show the state rather than a label that changes.
  • Give an icon-only toggle a `label`: it becomes the accessible name, and the pressed state is announced separately.
  • Use `type="multiple"` when the choices are independent, and `type="single"` when exactly one can hold.

Don't

  • Use a `Toggle` to submit a form — that is a `Button`.
  • Use a `Toggle` for an on/off setting that persists — that is a `Switch`.
  • Put a `ToggleGroup` beside a `SegmentedControl` in one toolbar: they look similar and mean different things, one a set of independent options and the other a single value.

Accessibility

A `Toggle` is a two-state button that reports `aria-pressed`, so assistive technology hears the state rather than a changed label. A `ToggleGroup` is a roving-focus composite where each item keeps its own pressed state; `type="single"` behaves as a radio group and always has one choice.

ButtonGroup and Toolbar are one module, documented together on the ButtonGroup page.

Related

Luc UI v1.0Toggledark theme