Components Forms
Switch
StableAn on/off toggle for settings that take effect immediately.
Use Switch for binary settings that apply as soon as they change, like enabling automatic deployment or two-factor authentication. If the change only applies when a form is submitted, use Checkbox instead.
Overview
Automatic deployment
import { Switch } from '@bindshq/stance-react';
export function Basic() {
return <Switch label="Automatic deployment" defaultChecked />;
}Light, dark and high contrast
Every Stance component is designed and tested in all three appearance modes.
Automatic deployment
Automatic deployment
Automatic deployment
Import
import { Switch } from '@bindshq/stance-react';Platforms
Switch has native counterparts. They share Stance tokens and intent, and use each platform’s own controls and conventions. The live previews on this page are the web implementation.
import { Switch } from '@bindshq/stance-react';Playground
Automatic deployment
<Switch />Examples
Require two-factor authenticationAll administrators must confirm sign-in with a second factor.
import { Switch } from '@bindshq/stance-react';
export function WithDescription() {
return (
<Switch
label="Require two-factor authentication"
description="All administrators must confirm sign-in with a second factor."
/>
);
}Settings list
Label at the start aligns switches in a column.
Campaign bannerShow the current campaign below every signature.Link trackingCount clicks on signature links.Signing remindersRemind signers every three days.
import * as React from 'react';
import { Switch } from '@bindshq/stance-react';
export function SettingsList() {
const [settings, setSettings] = React.useState({
banner: true,
tracking: false,
reminders: true,
});
const rows: { key: keyof typeof settings; label: string; description: string }[] = [
{
key: 'banner',
label: 'Campaign banner',
description: 'Show the current campaign below every signature.',
},
{ key: 'tracking', label: 'Link tracking', description: 'Count clicks on signature links.' },
{
key: 'reminders',
label: 'Signing reminders',
description: 'Remind signers every three days.',
},
];
return (
<div style={{ display: 'grid', gap: 20, width: '100%', maxWidth: 520 }}>
{rows.map((r) => (
<Switch
key={r.key}
label={r.label}
description={r.description}
labelPosition="start"
style={{ justifyContent: 'space-between', width: '100%' }}
checked={settings[r.key]}
onCheckedChange={(v) => setSettings((s) => ({ ...s, [r.key]: v }))}
/>
))}
</div>
);
}SmallDisabledDisabled on
Managed by your identity provider
import { FormField, Switch } from '@bindshq/stance-react';
export function States() {
return (
<div style={{ display: 'grid', gap: 14 }}>
<Switch size="sm" label="Small" defaultChecked />
<Switch label="Disabled" disabled />
<Switch label="Disabled on" disabled defaultChecked />
<FormField label="Single sign-on" description="Managed by your identity provider" readOnly>
<Switch defaultChecked />
</FormField>
</div>
);
}API reference
| Prop | Type | Default | Description |
|---|---|---|---|
checked | boolean | None | Controlled state. |
defaultChecked | boolean | false | Initial state. |
onCheckedChange | (checked: boolean) => void | None | Called with the new state. |
label | ReactNode | None | Visible label. Without it use aria-label or FormField. |
description | ReactNode | None | Help text, linked via aria-describedby. |
size | 'sm' | 'md' | 'md' | Track size. |
labelPosition | 'start' | 'end' | 'end' | Label before or after the track. |
name / value | string | value 'on' | Submit with forms via a hidden input. |
readOnly | boolean | false | Prevents changes but stays focusable. |
disabled | boolean | false | Disables the switch. |
Accessibility
- Renders a button with role="switch" and aria-checked, announced as "on" or "off".
- The label is linked with aria-labelledby and clicking it toggles the switch.
- State is shown by thumb position and fill, not colour alone, and remains clear in forced colours.
Keyboard
| Keys | Action |
|---|---|
| Space | Toggles the switch. |
| Enter | Toggles the switch. |
Usage guidelines
Do
- Describe the setting, not the action: “Automatic deployment”.
- Apply the change immediately and confirm it.
Don’t
- Use a switch inside a form that needs a Save button.