Switch

A switch turns something on. The difference from a checkbox is when it takes effect: a switch applies immediately, a checkbox states an intention that a form submission later carries out. If there is a Save button, it should probably be a checkbox.

import { Switch, SwitchContent, SwitchControl, SwitchThumb } from "ropav";

Notify me

size

 xssmmdlg

isDisabled

isReadOnly

<Switch>
  <SwitchContent>
    <SwitchControl>
      <SwitchThumb />
    </SwitchControl>
    Notify me
  </SwitchContent>
</Switch>

An icon in the thumb

SwitchIcon sits inside SwitchThumb and rides along with it. Use it when the two states need to be told apart without reading the label — and remember that the icon moves rather than changing, so it says "this is a switch", not "this is on".

Sync on save

Do not disturb

switch-icon.vue

<script setup lang="ts">
import {
  IconClose,
  IconPlus,
  Switch,
  SwitchContent,
  SwitchControl,
  SwitchIcon,
  SwitchThumb,
} from "ropav";
</script>

<template>
  <Switch default-selected>
    <SwitchContent>
      <SwitchControl>
        <SwitchThumb>
          <SwitchIcon>
            <IconPlus />
          </SwitchIcon>
        </SwitchThumb>
      </SwitchControl>
      Sync on save
    </SwitchContent>
  </Switch>

  <Switch>
    <SwitchContent>
      <SwitchControl>
        <SwitchThumb>
          <SwitchIcon>
            <IconClose />
          </SwitchIcon>
        </SwitchThumb>
      </SwitchControl>
      Do not disturb
    </SwitchContent>
  </Switch>
</template>

Accessibility

• The underlying control is a native checkbox with a switch role, so the state is the browser's to report rather than something the component announces.
• SwitchContent puts the label inside the control, so the whole row toggles.
• Under Forced Colors Mode the track and thumb are redrawn with system colours, because the fill that normally separates on from off is stripped there.

API

Switch

Prop	Type	Default	Description
ariaDescribedby	string	—	Ids of the elements that describe the switch, on top of any nested help text.
ariaLabel	string	—	Accessible name, for a switch with no visible label.
ariaLabelledby	string	—	Ids of the elements that name the switch.
defaultSelected	boolean	—	Whether the switch starts on, when it is uncontrolled.
form	string	—	id of the form to submit with, for a switch rendered outside it.
id	string	—	Lands on the hidden input rather than on the wrapper, because the input is the switch as far as assistive technology is concerned.
isDisabled	boolean	—	Whether the switch is disabled — no interaction, no submission.
isInvalid	boolean	—	Whether the value fails validation. Setting it either way takes the field over: false claims the switch is valid and shadows validate, the browser and the server alike.
isReadOnly	boolean	—	Whether the value can be read but not changed.
isRequired	boolean	—	Whether the switch has to be on for the form to submit.
isSelected	boolean	—	Whether the switch is on. Makes the switch controlled.
name	string	—	Name submitted with the form.
size	"xs" | "sm" | "md" | "lg"	"md"	Size of the control.
validate	ValidationFunction<boolean>	—	Checks the value and returns a message when it is not acceptable.
validationBehavior	"aria" | "native"	"native"	How the switch reports validation. Inherited from the surrounding form when unset.
value	string	"on"	Value submitted with the form while the switch is on.

The default slot receives:

Slot prop	Type
isDisabled	boolean
isInvalid	boolean
isReadOnly	boolean
isRequired	boolean
isSelected	boolean

Event	Payload
change	boolean
update:isSelected	boolean

SwitchContent

The default slot receives:

Slot prop	Type
isDisabled	boolean
isFocused	boolean
isFocusVisible	boolean
isHovered	boolean
isInvalid	boolean
isPressed	boolean
isReadOnly	boolean
isRequired	boolean
isSelected	boolean

SwitchControl

Slots: default.

SwitchIcon

Slots: default.

SwitchThumb

Slots: default.