Switch

A toggle control that allows users to turn a setting on or off, with support for labels, validation states, and loading states.

Import

tsx

import { Switch } from "asheeui";

Usage

tsx

import { Switch } from "asheeui";

export default function Basic() {
  return <Switch label="Enable notifications" />;
}

Examples

Default checked

Enabled by default

Controlled

Controlled switch

Checked: false

With label

Dark mode

With description

Email notifications

Receive email updates about your account

Inheritance

Switch extends the <Input/> component and inherits all of its layout and field props and functionality. This means you can use any Input prop with Switch, including:

size, color, radius
label, labelAlign, description, message
status, required, isLoading, disabled
className, and all native input attributes

Reference: For a complete list of inherited props with detailed descriptions, see the Input documentation.

What Switch adds

Feature	Description
Toggle State	Controlled (`checked`) and uncontrolled (`defaultChecked`) toggle states
Toggle Callback	Custom `onChange` receiving the boolean checked state and change event
Track & Thumb Layout	Custom toggle track and sliding thumb structure

What Switch modifies

Modification	Description
`radius`	Defaults to `"full"` to render a pill-shaped track
`onChange`	Receives `(checked: boolean, event: ChangeEvent<HTMLInputElement>)` instead of standard input value changes

What Switch does not inherit

The following Input props are not available on Switch:

Prop	Reason
`variant`	Not applicable - Switch uses a custom track layout instead of text input variants
`startContent` / `endContent`	Not applicable - content slots are replaced by the switch track and thumb
`type`	Not applicable - Switch is fixed to a checkbox with `role="switch"`
`value` / `defaultValue`	Replaced with `checked` / `defaultChecked`

All other Input props are fully supported. See the Input documentation for the complete list.

Props

Prop	Type	Default	Description
`checked`	`boolean`	None	Controlled checked state
`defaultChecked`	`boolean`	`false`	Default checked state for uncontrolled usage
`onChange`	`(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void`	None	Callback when toggled

Global Configuration

Switch reads defaults from four places, in this order of precedence:

Instance prop: set directly on <Switch/>
Component config: components.switch in your ashee.config
Theme default: defaultColor / defaultRadius in your ashee.config
Built-in fallback: component's internal default values

Component config

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    switch: {
      size: "md",
      color: "primary",
      radius: "full",
      labelAlign: "left",
    },
  },
});

Built-in fallbacks

{
  size: "md",
  radius: "full",
  color: "primary",
  status: "default",
  labelAlign: "left",
}

Accessibility

Renders a native <input type="checkbox"> with role="switch"
Uses aria-checked to indicate state
Uses aria-invalid for error states
Uses aria-busy for loading state
Uses aria-disabled for disabled state
Implements focus-visible rings for keyboard navigation
Labels are properly associated with the switch via htmlFor/id
Supports keyboard interaction with Space and Enter keys

Notes

Controlled vs Uncontrolled: Use checked/onChange for controlled usage, or defaultChecked for uncontrolled.
Status Colors: When status is set to error, success, or warning, the switch border reflects the status color.
Loading State: When isLoading is true, the switch is disabled and shows reduced opacity.
Color: The switch uses the color prop for the checked state background color.
Radius: The full radius creates a pill-shaped switch, which is the default behavior.
Field Shell Integration: Switch integrates with FieldShell to provide consistent layout handling for labels, descriptions, and validation messages.