Animated Switch

Use Animated Switch for a binary setting that changes immediately. It uses Base UI switch behavior with a responsive thumb press, an interruptible state transition, and optional thumb drag interaction.

Preview

Reduce motion:Off

Tune:Off

Inspect

Installation

Base UI Motion

npx shadcn@latest add @sona-ui/animated-switch

Basic usage

notifications-switch.tsx

import AnimatedSwitch from "@/components/ui/animated-switch/animated-switch";
 
export function NotificationsSwitch() {
return <AnimatedSwitch defaultChecked aria-label="Enable notifications" />;
}

Examples

Controlled state

Use checked and onCheckedChange when the switch reflects application state.

controlled-switch.tsx

"use client";
 
import { useState } from "react";
import AnimatedSwitch from "@/components/ui/animated-switch/animated-switch";
 
export function ControlledSwitch() {
const [checked, setChecked] = useState(false);
 
return (
  <AnimatedSwitch
    checked={checked}
    onCheckedChange={setChecked}
    aria-label="Enable notifications"
  />
);
}

Size, availability, and errors

Choose sm, md, or lg for the control size. Use disabled only when the setting cannot currently be changed.

Use error when a setting cannot be changed because it needs attention. Both disabled and error switches give a brief nudge on pointer interaction. Error remains focusable and exposes aria-invalid so its state is available to assistive technology.

Drag interaction

The thumb can be dragged between states, while tapping the track continues to toggle immediately. Set enableDrag={false} when the switch appears inside another horizontal drag interaction.

Usage


"use client";
 
import AnimatedSwitch from "@/components/ui/animated-switch/animated-switch";
 
export default function AnimatedSwitchDemo() {
  return <AnimatedSwitch defaultChecked size="lg" />;
}

API

Property	Type	Default	Description
`checked`	`boolean`	`—`	Controlled checked state.
`defaultChecked`	`boolean`	`false`	Initial checked state for uncontrolled usage.
`onCheckedChange`	`(checked: boolean) => void`	`—`	Callback fired when the checked state changes.
`disabled`	`boolean`	`false`	Whether the switch is disabled.
`error`	`boolean`	`false The switch remains focusable so assistive technology can announce its invalid state.`	Whether the switch is in an error state and cannot be changed.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	The size of the switch.
`enableDrag`	`boolean`	`true`	Whether the thumb can be dragged between states.
`className`	`string`	`—`	Additional classes for the switch track.

Accessibility

Provide an accessible name with a visible label or aria-label. The switch supports keyboard interaction, exposes its checked state to assistive technology, and keeps the same tap and keyboard behavior when drag interaction is disabled. Error switches expose aria-invalid and aria-disabled; disabled switches use the native disabled state.

Styling

Use the size and class name options to fit the control into a settings row or compact toolbar. Reduced-motion preferences remove the press deformation, state transition, and blocked-state nudge while preserving static disabled and error cues.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Sona UI