> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Switch
> A labeled on or off control with controlled and uncontrolled state.
export const StoryEmbed = ({storyId, title, height = 120}) => <>
Open in Storybook
;
Use `Switch` for an on or off preference. Give the control a visible label or an accessible name.
## Usage
### Uncontrolled state
Use `defaultChecked` to set the initial checked state. The switch owns subsequent changes.
```tsx theme={null}
import { useId } from 'react';
import { Switch } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';
export const NotificationsPreference = () => {
const switchId = useId();
return (
);
};
```
## Visual choices
Compare the two sizes in on, off, disabled, read-only, and focus states. Use the enabled examples to try toggling.
## Controlled state
Pass `checked` and update it with `onCheckedChange` to own the same preference in React state.
```tsx theme={null}
import { useId, useState } from 'react';
import { Switch } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';
export const NotificationsPreference = () => {
const switchId = useId();
const [checked, setChecked] = useState(false);
return (
);
};
```
`onCheckedChange` receives the next boolean and event details. The `size` prop accepts `sm` or `md` and defaults to `md`.
For a consistent full-width row with an icon, description, and switch, use [SettingsRow](/ui/components/settings/settings-row).
## Keyboard and forms
Tab moves focus to the switch; Space toggles it. Clicking its associated label also toggles it. Use `disabled` to prevent interaction or `readOnly` to retain a focusable control whose value cannot be changed.
A named switch submits its value when checked. Use `value` to customize that value, and `uncheckedValue` if the form should also submit a value when it is off.
## Parts and custom content
`Switch` assembles the styled root and its default thumb. Use `Switch.Root` with `Switch.Thumb` to own the thumb content. Root owns state and track appearance; Thumb renders the content you supply.
```tsx theme={null}
import { Switch } from 'twenty-ui/primitives/input';
export const CustomPreference = () => (
);
```
`SwitchRootProps` and `SwitchThumbProps` are public types exported from `twenty-ui/primitives/input`. Both parts accept native attributes, handlers, refs, `render`, and state-based `className` and `style` callbacks. Root's `ref` targets the visible control; `inputRef` targets the native input. The part ref targets its rendered element. Pass `nativeButton` with `render={}` when replacing Root with a button. Appearance props belong on Root; explicit classes and styles are merged with the defaults.
Thumb receives the current checked, disabled, readOnly, required, and Field state. Its position follows the reading direction.
The callable assembly and its `SwitchProps` type remain supported. Replace the assembly with Root and its part when supplying custom thumb content instead of appending another part to the assembly's children.
For controlled form reset, handle the form's `onReset` and restore `checked` to your initial value. Base UI 1.8 does not restore uncontrolled component state on native form reset. `required`, `form`, `value`, and `uncheckedValue` keep the upstream native input behavior.
## Props
The reference includes component-specific and inherited Base UI props. Native attributes such as `aria-label` and `data-*` are also accepted.
Whether the switch is currently active.
To render an uncontrolled switch, use the `defaultChecked` prop instead.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Whether the switch is initially active.
To render a controlled switch, use the `checked` prop instead.
Whether the component should ignore user interaction.
Identifies the form that owns the hidden input.
Useful when the switch is rendered outside the form.
The id of the hidden input element.
When `nativeButton` is `true`, the id is applied to the root element.
A ref to access the hidden `` element.
Identifies the field when a form is submitted.
Whether the component renders a native `
Event handler called when the switch is activated or deactivated.
Whether the user should be unable to activate or deactivate the switch.
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.
Whether the user must activate the switch before submitting a form.
Visual size of the switch.
Style applied to the element, or a function that
returns a style object based on the component's state.
The value submitted with the form when the switch is off.
By default, unchecked switches do not submit any value, matching native checkbox behavior.
The value submitted with the form when the switch is on.
By default, switch submits the "on" value, matching native checkbox behavior.
### Switch.Root
Whether the switch is currently active.
To render an uncontrolled switch, use the `defaultChecked` prop instead.
CSS class applied to the element, or a function that
returns a class based on the component's state.
Whether the switch is initially active.
To render a controlled switch, use the `checked` prop instead.
Whether the component should ignore user interaction.
Identifies the form that owns the hidden input.
Useful when the switch is rendered outside the form.
The id of the hidden input element.
When `nativeButton` is `true`, the id is applied to the root element.
A ref to access the hidden `` element.
Identifies the field when a form is submitted.
Whether the component renders a native `
Event handler called when the switch is activated or deactivated.
Whether the user should be unable to activate or deactivate the switch.
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.
Whether the user must activate the switch before submitting a form.
Visual size of the switch.
Style applied to the element, or a function that
returns a style object based on the component's state.
The value submitted with the form when the switch is off.
By default, unchecked switches do not submit any value, matching native checkbox behavior.
The value submitted with the form when the switch is on.
By default, switch submits the "on" value, matching native checkbox behavior.
### Switch.Thumb
CSS class applied to the element, or a function that
returns a class based on the component's state.
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.
Style applied to the element, or a function that
returns a style object based on the component's state.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.