1. Components
  2. Forms and inputs
  3. Switch

Switch

Switches allow users to turn an individual option on or off.

<Switch>Focus mode</Switch>

Installation

npx dotui-cli@latest add switch

Usage

Use switch for communicating activation (e.g. on/off states), while checkboxes are best used for communicating selection (e.g. multiple table rows). Switches, unlike checkboxes, can't have an error state.

import { Switch } from "@/components/core/switch";
 
<Switch>Focus mode</Switch>;
import {
  SwitchRoot,
  SwitchIndicator,
  SwitchThumb,
} from "@/components/core/switch";
 
<SwitchRoot>
  <SwitchIndicator>
    <SwitchThumb />
  </SwitchIndicator>
  <span>Focus mode</span>
</SwitchRoot>;

Options

Variant

Use the variant prop to control the visual style of the switch.

import React from "react";
import { Switch } from "@/components/dynamic-core/switch";

export default function Demo() {
  return <Switch variant="card">Focus mode</Switch>;
}

Size

Use the size prop to control the size of the switch. The default variant is "md".

<Switch size="sm" />
<Switch size="md" />
<Switch size="lg" />

Label

A visual label can be provided using the component children or a hidden label using aria-label prop.

<Switch>Focus mode</Switch>
<Switch aria-label="Focus mode" />

Disabled

Use the isDisabled prop to disable the switch.

<Switch isDisabled>Focus Mode</Switch>

Uncontrolled

The defaultSelected prop can be used to set the default state.

<Switch defaultSelected>Airplane Mode</Switch>

Controlled

Use the isSelected and onChange props to control the value of the input.

You are on focus mode.

const [isSelected, setSelected] = React.useState(true);
return (
  <Switch isSelected={isSelected} onChange={setSelected}>
    Airplane Mode
  </Switch>
)

Composition

If you need to customize things further, you can drop down to the composition level.

<SwitchRoot>
  <SwitchIndicator>
    <SwitchThumb />
  </SwitchIndicator>
</SwitchRoot>

API Reference

PropTypeDefaultDescription
size"sm" | "md" | "lg""md"The size of the switch.
inputRefMutableRefObject<HTMLInputElement>-A ref for the HTML input element.
defaultSelectedboolean-Whether the element should be selected (uncontrolled).
isSelectedboolean-Whether the element should be selected (controlled).
valuestring-The value of the input element, used when submitting an HTML form.
isDisabledboolean-Whether the input is disabled.
isReadOnlyboolean-Whether the input can be selected but not changed by the user.
autoFocusboolean-Whether the element should receive focus on render.
namestring-The name of the input element, used when submitting an HTML
childrenReactNode | (values: CheckboxRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode-The children of the component. A function may be provided to alter the children based on component state.
EventTypeDescription
onChange(isSelected: boolean) => voidHandler that is called when the Switch's selection state changes.
onFocus(e: FocusEvent<Target>) => voidHandler that is called when the Switch receives focus.
onBlur(e: FocusEvent<Target>) => voidHandler that is called when the Switch loses focus.
onFocusChange(isFocused: boolean) => voidHandler that is called when the Switch's focus status changes.
onKeyDown(e: KeyboardEvent) => voidHandler that is called when a key is pressed.
onKeyUp(e: KeyboardEvent) => voidHandler that is called when a key is released.
onHoverStart(e: HoverEvent) => voidHandler that is called when a hover interaction starts.
onHoverEnd(e: HoverEvent) => voidHandler that is called when a hover interaction ends.
onHoverChange(isHovering: boolean) => voidHandler that is called when the hover state changes.
Data attributeDescription
[data-selected]Whether the switch is selected.
[data-hovered]Whether the switch is currently hovered with a mouse.
[data-pressed]Whether the switch is currently in a pressed state.
[data-focused]Whether the switch is focused, either via a mouse or keyboard.
[data-focus-visible]Whether the switch is keyboard focused.
[data-disabled]Whether the switch is disabled.
[data-readonly]Whether the switch is read only.

Accessibility

Keyboard interactions

KeyDescription
Space EnterToggles the component's state.

Built by mehdibha. The source code is available on GitHub.