1. Components
  2. Inputs
  3. Switch

Switch

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

Aria docsAria API ReferenceReport 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.

Options

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 defaultValue 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>
)

API Reference

PropTypeDefaultDescription
size
"sm" | "md" | "lg"
"md"
The size of the switch.
inputRef
MutableRefObject<HTMLInputElement>
-
A ref for the HTML input element.
defaultSelected
boolean
-
Whether the element should be selected (uncontrolled).
isSelected
boolean
-
Whether the element should be selected (controlled).
value
string
-
The value of the input element, used when submitting an HTML form.
isDisabled
boolean
-
Whether the input is disabled.
isReadOnly
boolean
-
Whether the input can be selected but not changed by the user.
autoFocus
boolean
-
Whether the element should receive focus on render.
name
string
-
The name of the input element, used when submitting an HTML
children
ReactNode | (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) => void
Handler that is called when the Switch's selection state changes.
onFocus
(e: FocusEvent<Target>) => void
Handler that is called when the Switch receives focus.
onBlur
(e: FocusEvent<Target>) => void
Handler that is called when the Switch loses focus.
onFocusChange
(isFocused: boolean) => void
Handler that is called when the Switch's focus status changes.
onKeyDown
(e: KeyboardEvent) => void
Handler that is called when a key is pressed.
onKeyUp
(e: KeyboardEvent) => void
Handler that is called when a key is released.
onHoverStart
(e: HoverEvent) => void
Handler that is called when a hover interaction starts.
onHoverEnd
(e: HoverEvent) => void
Handler that is called when a hover interaction ends.
onHoverChange
(isHovering: boolean) => void
Handler 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 Enter
Toggles the component's state.

Last updated on 10/11/2024

Radio GroupSlider