Components

Switch

A control for toggling a single setting on or off.

Basic example

Row-level securityEnforce access policies on every query.

RealtimeStream changes to subscribed clients.

Point-in-time recoveryAvailable on the Scale plan.

Installation

Choose the package when you want centralized updates, or copy the source through the registry when you want local ownership.

@constructive-io/ui

Install the package, import its global tokens once, then use this exact subpath.

# install

pnpm add @constructive-io/ui

# app/globals.css

@import '@constructive-io/ui/globals.css';

# import

import { Switch } from '@constructive-io/ui/switch';

When to use

Use Switch for a binary setting whose effect applies immediately, such as enabling notifications or row-level security.
Use Checkbox for acknowledgments, form choices applied on submit, or selecting items from a set.

Basic usage

Associate Switch with a visible Label by matching id and htmlFor. Use defaultChecked for a locally owned initial setting.

npm source

tsx

'use client';
import { Label } from '@constructive-io/ui/label';
import { Switch } from '@constructive-io/ui/switch';
export function BasicSwitchDemo() {
    return (<div className="flex items-center gap-3">
        <Switch id="switch-notifications" defaultChecked/>
        <Label htmlFor="switch-notifications">Email notifications</Label>
      </div>);
}

Controlled and uncontrolled checked state

Use defaultChecked when Switch can own its state. Pass checked and onCheckedChange when the setting is synchronized with application or server state.

Controlled and uncontrolled checked state

Realtime updates

Realtime updates are on.

Examples

Settings listPair each switch with a clear setting name and supporting text, and leave unavailable settings visible when their context matters.

Row-level securityEnforce access policies on every query.

RealtimeStream changes to subscribed clients.

Point-in-time recoveryAvailable on the Scale plan.

Accessibility

Give every Switch an accessible name with a visible Label, aria-label, or aria-labelledby.
Connect supporting text or an unavailable-setting explanation with aria-describedby when it adds information beyond the Label.
Describe the setting rather than the gesture. The checked state already communicates on or off, so labels such as “Enable notifications” remain clear in either state.
Apply the setting when the checked value changes. If changes are deferred until form submission, Checkbox is usually the clearer control.

API Reference

Constructive-specific behavior is listed here. Each part links to its inherited platform or primitive contract.

Switch

Base UI switch root with a Constructive track, thumb, and hidden form input.

Prop	Type	Default	Description
checked	boolean	—	Controlled on or off state.
defaultChecked	boolean	false	Initial uncontrolled state.
onCheckedChange	(checked: boolean, eventDetails) => void	—	Runs when the checked state changes.
disabled	boolean	false	Prevents interaction and form changes.
readOnly	boolean	false	Prevents changing the state while retaining focusability.
required	boolean	false	Requires the switch to be on before form submission.
name	string	—	Name used by the hidden form input.
value	string	—	Value submitted when the switch is on.
uncheckedValue	string	—	Optional value submitted when the switch is off.

Also accepts Base UI Switch props.