메인 콘텐츠로 이동

Switch

A toggle control for binary on/off settings.

Overview

The Switch component provides a visual toggle for activating or deactivating a setting. Built on a headless accessibility foundation, it supports multiple sizes, semantic color variants, and label position configuration. It supports both controlled usage via checked and onCheckedChange, and uncontrolled usage via defaultChecked.

Switch represents an instant toggle — use it for settings that take effect immediately without a form submission (e.g., "Enable notifications", "Dark mode"). For changes that require a save action, use Checkbox instead.

Accessibility

  • Renders with role="switch" and aria-checked for assistive technologies.
  • Space toggles the switch. Tab moves focus to the next focusable element.
  • When label is provided, it is automatically associated with the switch via the id attribute.
  • When disabled, the switch is visually dimmed and excluded from keyboard navigation.

Import

import { Switch } from "@cocso-ui/react";

Default

A basic switch controlled with local state.

"use client";

import { Switch } from "@cocso-ui/react";
import { useState } from "react";

export default function SwitchDefault() {
  const [checked, setChecked] = useState(false);

  return (
    <div className="flex flex-col gap-4 p-4">
      <Switch checked={checked} label="Enable notifications" onCheckedChange={setChecked} />
    </div>
  );
}

Size

Three sizes are available. Choose based on surrounding layout density.

import { Switch } from "@cocso-ui/react";

export default function SwitchSizes() {
  return (
    <div className="flex flex-col gap-4 p-4">
      <Switch defaultChecked label="Large" size="large" />
      <Switch defaultChecked label="Medium" size="medium" />
      <Switch defaultChecked label="Small" size="small" />
    </div>
  );
}

Variant

Color variants convey the semantic meaning of the toggle. Use primary for general settings and state variants for actions with specific outcomes.

import { Switch } from "@cocso-ui/react";

export default function SwitchVariants() {
  return (
    <div className="flex flex-col gap-4 p-4">
      <Switch defaultChecked label="Primary" variant="primary" />
      <Switch defaultChecked label="Success" variant="success" />
      <Switch defaultChecked label="Error" variant="error" />
      <Switch defaultChecked label="Warning" variant="warning" />
      <Switch defaultChecked label="Info" variant="info" />
    </div>
  );
}

Label Position

Use the position prop to control whether the label appears to the left or right of the switch. The default is right.

Disabled

Set disabled to prevent the user from toggling the switch.

API Reference

PropTypeDefaultDescription
checkedboolean-Controlled checked state. Use together with `onCheckedChange` for full control over toggle behavior.
defaultCheckedboolean-Initial checked state for uncontrolled usage. The component manages its own state internally.
onCheckedChange(checked: boolean) => void-Callback invoked when the user toggles the switch. Receives the new boolean value.
labelstring-Label text displayed next to the switch, automatically associated for screen reader accessibility.
size"small" | "medium" | "large""medium"Controls the track and thumb dimensions. Use `large` for prominent settings panels and `small` for compact layouts.
variant"primary" | "success" | "error" | "warning" | "info""primary"Controls the track color when checked. Use semantic variants to convey the meaning of the toggle (e.g., `error` for a destructive setting).
position"left" | "right""right"Positions the label relative to the switch. Use `left` in settings panels with labels on the left and `right` for inline toggles.
disabledbooleanfalsePrevents interaction and visually dims the switch. Disabled switches are excluded from keyboard navigation.
idstring-The HTML id attribute.