1. Components
  2. Forms and inputs
  3. Switch

Switch

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

Aria docsReport an issueEdit this page
<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.
Radio GroupSlider
dotUI

Bringing singularity to the web.

Community

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