---
title: Toggle
subtitle: A two-state button that can be on or off.
description: A high-quality, unstyled React toggle component that displays a two-state button that can be on or off.
---
# Toggle
A high-quality, unstyled React toggle component that displays a two-state button that can be on or off.
## Demo
### Tailwind
This example shows how to implement the component using Tailwind CSS.
```tsx
/* index.tsx */
'use client';
import * as React from 'react';
import { Toggle } from '@base-ui/react/toggle';
export default function ExampleToggle() {
return (
{
if (state.pressed) {
return (
);
}
return (
);
}}
/>
);
}
function HeartFilledIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
function HeartOutlineIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
### CSS Modules
This example shows how to implement the component using CSS Modules.
```css
/* index.module.css */
.Panel {
display: flex;
gap: 1px;
border: 1px solid var(--color-gray-200);
background-color: var(--color-gray-50);
border-radius: 0.375rem;
padding: 0.125rem;
}
.Button {
box-sizing: border-box;
display: flex;
align-items: center;
justify-content: center;
width: 2rem;
height: 2rem;
padding: 0;
margin: 0;
outline: 0;
border: 0;
border-radius: 0.25rem;
background-color: transparent;
color: var(--color-gray-600);
user-select: none;
&:focus-visible {
background-color: transparent;
outline: 2px solid var(--color-blue);
outline-offset: -1px;
}
@media (hover: hover) {
&:hover {
background-color: var(--color-gray-100);
}
}
&:active {
background-color: var(--color-gray-200);
}
&[data-pressed] {
color: var(--color-gray-900);
}
}
.Icon {
width: 1.25rem;
height: 1.25rem;
}
```
```tsx
/* index.tsx */
'use client';
import * as React from 'react';
import { Toggle } from '@base-ui/react/toggle';
import styles from './index.module.css';
export default function ExampleToggle() {
return (
{
if (state.pressed) {
return (
);
}
return (
);
}}
/>
);
}
function HeartFilledIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
function HeartOutlineIcon(props: React.ComponentProps<'svg'>) {
return (
);
}
```
## Anatomy
Import the component and use it as a single part:
```jsx title="Anatomy"
import { Toggle } from '@base-ui/react/toggle';
` element.
**Toggle Props:**
| Prop | Type | Default | Description |
| :-------------- | :----------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| value | `string` | - | A unique string that identifies the toggle when used
inside a toggle group. |
| defaultPressed | `boolean` | `false` | Whether the toggle button is currently pressed.
This is the uncontrolled counterpart of `pressed`. |
| pressed | `boolean` | - | Whether the toggle button is currently pressed.
This is the controlled counterpart of `defaultPressed`. |
| onPressedChange | `((pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void)` | - | Callback fired when the pressed state is changed. |
| nativeButton | `boolean` | `true` | Whether the component renders a native `` element when replacing it
via the `render` prop.
Set to `false` if the rendered element is not a button (for example, ``). |
| disabled | `boolean` | `false` | Whether the component should ignore user interaction. |
| className | `string \| ((state: Toggle.State) => string \| undefined)` | - | CSS class applied to the element, or a function that
returns a class based on the component's state. |
| style | `React.CSSProperties \| ((state: Toggle.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that
returns a style object based on the component's state. |
| render | `ReactElement \| ((props: HTMLProps, state: Toggle.State) => ReactElement)` | - | Allows you to replace the component's HTML element
with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
**Toggle Data Attributes:**
| Attribute | Type | Description |
| :----------- | :--- | :----------------------------------------- |
| data-pressed | - | Present when the toggle button is pressed. |
### Toggle.Props
Re-export of [Toggle](/react/components/toggle.md) props.
### Toggle.State
```typescript
type ToggleState = {
/** Whether the toggle is currently pressed. */
pressed: boolean;
/** Whether the toggle should ignore user interaction. */
disabled: boolean;
};
```
### Toggle.ChangeEventReason
```typescript
type ToggleChangeEventReason = 'none';
```
### Toggle.ChangeEventDetails
```typescript
type ToggleChangeEventDetails = {
/** The reason for the event. */
reason: 'none';
/** The native event associated with the custom event. */
event: Event;
/** Cancels Base UI from handling the event. */
cancel: () => void;
/** Allows the event to propagate in cases where Base UI will stop the propagation. */
allowPropagation: () => void;
/** Indicates whether the event has been canceled. */
isCanceled: boolean;
/** Indicates whether the event is allowed to propagate. */
isPropagationAllowed: boolean;
/** The element that triggered the event, if applicable. */
trigger: Element | undefined;
};
```
## Canonical Types
Maps `Canonical`: `Alias` — Use Canonical when its namespace is already imported; otherwise use Alias.
- `Toggle.State`: `ToggleState`
- `Toggle.Props`: `ToggleProps`
- `Toggle.ChangeEventReason`: `ToggleChangeEventReason`
- `Toggle.ChangeEventDetails`: `ToggleChangeEventDetails`