Toggle

Overview

The Toggle component is a button-like control for two-state actions such as formatting, view options, and compact toolbar settings. It owns the default and outline pressed states, so grouped toggles can reuse the same surface behavior.

Usage

import { Toggle } from "@tilt-legal/cubitt-components/toggle";

<Toggle aria-label="Toggle bold">
  <TextBold />
</Toggle>

Examples

Default

Default toggles behave like ghost buttons until pressed.

import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import { TextBold } from "@tilt-legal/cubitt-icons/ui/outline";

export default function Example() {
  return (
    <Toggle aria-label="Toggle bold">
      <TextBold />
    </Toggle>
  );
}

Outline

Use the outline variant when the toggle should carry a contextual bordered surface.

import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import { TextItalic } from "@tilt-legal/cubitt-icons/ui/outline";

export default function Example() {
  return (
    <Toggle aria-label="Toggle italic" variant="outline">
      <TextItalic />
    </Toggle>
  );
}

With Text

Toggles can include both an icon and a short label.

import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import {
  TextBold,
  TextItalic,
} from "@tilt-legal/cubitt-icons/ui/outline";

export default function Example() {
  return (
    <div className="flex items-center gap-2">
      <Toggle aria-label="Toggle bold">
        <TextBold />
        Bold
      </Toggle>
      <Toggle aria-label="Toggle italic" variant="outline">
        <TextItalic />
        Italic
      </Toggle>
    </div>
  );
}

Sizes

Toggles support sm, md, and lg sizes.

import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import {
  TextBold,
  TextItalic,
  TextUnderline,
} from "@tilt-legal/cubitt-icons/ui/outline";

export default function Example() {
  return (
    <div className="flex items-center gap-4">
      <Toggle aria-label="Toggle bold" size="sm" variant="outline">
        <TextBold />
      </Toggle>
      <Toggle aria-label="Toggle italic" size="md" variant="outline">
        <TextItalic />
      </Toggle>
      <Toggle aria-label="Toggle underline" size="lg" variant="outline">
        <TextUnderline />
      </Toggle>
    </div>
  );
}

URL State

Use URL state when the pressed value should be shareable or restored on refresh.

import { Toggle } from "@tilt-legal/cubitt-components/toggle";
import { TextBold } from "@tilt-legal/cubitt-icons/ui/outline";

export default function Example() {
  return (
    <Toggle
      aria-label="Toggle bold"
      defaultPressed={false}
      paramClearOnDefault
      paramName="demo-bold"
    >
      <TextBold />
      Bold
    </Toggle>
  );
}

API Reference

Toggle

Prop	Type	Default	Description
`pressed`	`boolean`	-	Controlled pressed state.
`defaultPressed`	`boolean`	`false`	Initial pressed state for uncontrolled usage.
`onPressedChange`	`(pressed: boolean) => void`	-	Called when the pressed state changes.
`disabled`	`boolean`	`false`	Disables the toggle.
`variant`	`"default" \| "outline"`	`"default"`	Visual style.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Toggle size.
`className`	`string`	-	Additional classes.
`children`	`React.ReactNode`	-	Toggle content.

URL State Props

Prop	Type	Default	Description
`paramName`	`string`	-	Search parameter name used for URL state.
`paramValue`	`boolean`	-	Controlled URL-backed value.
`onUrlValueChange`	`(pressed: boolean \| null) => void`	-	Called when the URL-backed value changes.
`paramClearOnDefault`	`boolean`	`true`	Removes the URL parameter when value matches the default.
`paramThrottle`	`number`	-	Throttles URL updates in milliseconds.
`paramDebounce`	`number`	-	Debounces URL updates in milliseconds.

Notes

Use aria-label for icon-only toggles.
Use pressed and onPressedChange for controlled state.
Use ToggleGroup when related toggles need coordinated keyboard navigation or shared selection state.

Toggle

URL State

On this page