Switch

An unstyled, accessible switch toggle component with compound composition.

Build fully custom switch toggle controls with complete control over layout and styling.

Notifications

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Switch with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with three sub-components: Root, Control, Thumb
Hidden native checkbox with role="switch" for full accessibility
Controlled and uncontrolled checked state
Invalid and disabled state support with data attributes

Usage#

import { Switch } from 'primereact/switch';

<Switch.Root>
    <Switch.Control>
        <Switch.Thumb />
    </Switch.Control>
</Switch.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Switch.Root as="label">
    <Switch.Control as="span">
        <Switch.Thumb as="span" />
    </Switch.Control>
</Switch.Root>

Default elements: Root=div, Control=div, Thumb=span.

Render Function Children#

Switch.Thumb accepts a render function as children, providing access to the component instance.

<Switch.Thumb>{(instance) => <span>{instance.switch?.state.checked ? 'ON' : 'OFF'}</span>}</Switch.Thumb>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

Off

/* Select a part to see its CSS selector for custom styling */

API#

SwitchRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: SwitchRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: SwitchRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`SwitchRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<SwitchRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: SwitchRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`checked`	`boolean`	—
When present, it specifies the input's checked state.
`defaultChecked`	`boolean`	—
The default value for the input when not controlled by `checked` and `onCheckedChange` .
`tabIndex`	`number`	—
Index of the element in tabbing order.
`value`	`unknown`	—
Value of the switch.
`disabled`	`boolean`	`false`
When present, it specifies that the element should be disabled.
`required`	`boolean`	`false`
When present, it specifies that the element is required.
`invalid`	`boolean`	`false`
When present, it specifies that the component should have invalid state style.
`inputId`	`string`	—
Identifier of the underlying input element.
`inputStyle`	`CSSProperties`	—
Inline style of the input field.
`inputClassName`	`string`	—
Style class of the input field.
`ariaLabel`	`string`	—
Establishes a string value that labels the component.
`ariaLabelledby`	`string`	—
Establishes relationships between the component and label(s) where its value should be one or more element IDs.
`onFocus`	`(event: FocusEvent<HTMLInputElement>) => void`	—
Callback function that is called when the switch is focused.
`onBlur`	`(event: FocusEvent<HTMLInputElement>) => void`	—
Callback function that is called when the switch loses focus.
`onCheckedChange`	`(event: SwitchRootChangeEvent) => void`	—
Callback fired when the switch's checked state changes.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"switch"`
`data-part`	`"root"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid

Defines passthrough(pt) options of Switch component.

label	type	description
root	SwitchRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.
input	SwitchRootPassThroughType<HTMLAttributes<HTMLElement>>	Used to pass attributes to the input's DOM element.
control	SwitchRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the control's DOM element.
thumb	SwitchRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the thumb's DOM element.

SwitchControl#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: SwitchControlInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: SwitchControlInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`SwitchControlInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<SwitchControlPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: SwitchControlInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"switch"`
`data-part`	`"control"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid

Defines passthrough(pt) options of SwitchControl component.

label	type	description
root	SwitchControlPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

SwitchThumb#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: SwitchThumbInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: SwitchThumbInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`SwitchThumbInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<SwitchThumbPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: SwitchThumbInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"switch"`
`data-part`	`"thumb"`
`data-checked`	Present when checked
`data-unchecked`	Present when unchecked
`data-disabled`	Present when disabled
`data-invalid`	Present when invalid

Defines passthrough(pt) options of SwitchThumb component.

label	type	description
root	SwitchThumbPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

Switch.Root renders a hidden native <input type="checkbox" role="switch"> that is announced as a switch by assistive technologies. The input reflects checked state via aria-checked. Provide an accessible name with aria-label, aria-labelledby, or an associated <label> element using inputId.

<label htmlFor="switch1">Notifications</label>
<Switch.Root inputId="switch1" />
 
<span id="switch2">Dark Mode</span>
<Switch.Root ariaLabelledby="switch2" />
 
<Switch.Root ariaLabel="Enable notifications" />

Keyboard Support#

Key	Function
`tab`	Moves focus to the switch.
`space`	Toggles the checked state.