Toggle

A two-state button that can be either on or off.

Toggles are primarily used to manage interface states (like text formatting in an editor or muting a track) rather than submitting form data. This ToggleBlock automatically manages the data-state and aria-pressed HTML attributes to ensure visual feedback and screen-reader accessibility are perfectly synced.

Explore the different variations of the Toggle component — each example shows a live preview with the exact code to copy.

Sizes

Usesize: to change the hit area and icon scale.

Installation

New project? Follow the installation guide to set up Tailwind CSS, shadcn, the cn helper and lucide-react, register the @algorize-ui registry once, then copy your styles from the Themes page.

Install Toggle

npx shadcn@latest add @algorize-ui/toggle

components/custom/blocks/ToggleBlock.tsx is written into your project. Copy any snippet from a Usage tab above and it runs.

Install dependencies

Nothing beyond the shared setup — Toggle needs only the cn helper and lucide-react, which the installation guide already put in place.

Examples

With text

children: can hold an icon and a label together when the toggle drives a named action.

pressed: is per-toggle — a toolbar is just independent toggles side by side, not a group component.

Disabled

Setdisabled: to lock the toggle in whatever state it is currently in.

Usage

Uncontrolled (Simple)

If you don't need to tightly bind the component to React state, you can let it manage its own internal state and just provide a defaultPressed value.

Controlled (Advanced)

If you are building complex interfaces (like a Rich Text Editor), you should control the state directly using the pressed and onPressedChange prop

Features

Explore the Toggle button's simple two-state functionality, perfect for on/off switches and boolean preferences with smooth transitions.

Customizable

Easily adapt the component's styling and behavior to fit your application's unique design system.

Accessible

Built with accessibility in mind, ensuring all users can interact with your application effectively.

Responsive

Fully responsive design that looks and works great across desktop, tablet, and mobile devices.

Performant

Optimized for maximum performance with minimal re-renders and efficient state management.

Best Practices & Guidelines

Usage Guidelines

Follow standard design principles when implementing this component. Ensure proper contrast, spacing, and context within your layout.

Props Reference

Component	Prop	Type	Default	Description
`Toggle`	`pressed`	`boolean`	`undefined`	The controlled pressed state of the toggle. If provided, the component relies entirely on this value.
`Toggle`	`defaultPressed`	`boolean`	`false`	The starting state when the component is uncontrolled.
`Toggle`	`onPressedChange`	`(pressed: boolean) => void`	`undefined`	Event handler called when the pressed state of the toggle changes.
`Toggle`	`variant`	`"default" \| "outline" \| "ghost"`	`"default"`	The visual style variant. `ghost` is highly recommended when clustering multiple toggles together in a toolbar.
`Toggle`	`size`	`"sm" \| "md" \| "lg"`	`"md"`	Adjusts the height, horizontal padding, and text-size of the toggle button.
`Toggle`	`className`	`string`	`undefined`	Standard Tailwind CSS overrides.