Switch
Switches allow users to toggle a setting or preference between enabled and disabled states.
Quick Start
Use a Switch when users need to enable or disable a setting.
1import { Switch } from "@ecos/ui"; 2 3<Switch 4 label="Email notifications" 5/>
Controlled Usage
Control the switch externally using the checked and onCheckedChange props.
1const [enabled, setEnabled] = useState(false); 2 3<Switch 4 label="Email notifications" 5 checked={enabled} 6 onCheckedChange={setEnabled} 7/>
Labels
Provide a label to clearly communicate the purpose of the switch.
1<Switch 2 label="Email notifications" 3/>
Help Text
Use help text to provide additional guidance or context.
Receive product updates and announcements.
1<Switch 2 label="Email notifications" 3 helpText="Receive product updates and announcements." 4/>
States
Use the state prop to communicate validation and feedback states.
Please enable notifications.
Notifications enabled.
1<Switch 2 label="Email notifications" 3 state="error" 4 helpText="Please enable notifications." 5/> 6 7<Switch 8 label="Email notifications" 9 state="success" 10 helpText="Notifications enabled." 11/>
Required Fields
Use the required prop to indicate a mandatory selection.
1<Switch 2 label="Accept terms and conditions" 3 required 4/>
Checked State
A switch can be rendered in an enabled state using the checked prop.
1<Switch 2 label="Email notifications" 3 checked 4/>
Disabled State
Disable the switch when interaction is unavailable.
1<Switch 2 label="Email notifications" 3 disabled 4/>
Disabled Checked State
Disabled switches can still indicate an active setting.
1<Switch 2 label="Email notifications" 3 disabled 4 checked 5/>
Custom IDs
Supply an id when integrating with forms, testing, or analytics.
1<Switch 2 id="marketing-emails" 3 label="Marketing emails" 4/>
Switch Without Label
Switches can be rendered without a label when used within custom layouts.
1<Switch />
API Reference
Property | Type | Default | Description |
|---|---|---|---|
| label | string | - | Label displayed alongside the switch. |
| helpText | string | - | Additional descriptive text displayed below the switch. |
| state | "default" | "error" | "success" | "default" | Controls the validation state styling applied to the label and help text. |
| required | boolean | false | Displays a required indicator alongside the label. |
| id | string | "switch-" + label | Unique identifier used to associate the label with the switch. |
| checked | boolean | - | Controls the checked state of the switch. |
| defaultChecked | boolean | false | Sets the initial checked state when uncontrolled. |
| onCheckedChange | (checked: boolean) => void | - | Called when the checked state changes. |
| disabled | boolean | false | Prevents user interaction. |
| className | string | - | Additional classes applied to the switch root element. |
Visual Reference
Configuration | Preview |
|---|---|
| Default | |
| With Help Text | Receive product updates and announcements. |
| Error State | Please enable notifications. |
| Success State | Notifications enabled. |
| Checked | |
| Required | |
| Disabled | |
| Disabled Checked | |
| Without Label |