Switch

An on/off switch for a setting that applies at once. On settings screens, put it in a Settings list; in a form, pair it with a label in a horizontal Field. For a choice that applies on submit, use a Checkbox.

Installation

bun add @harmo-ui/css @harmo-ui/react

npm install @harmo-ui/css @harmo-ui/react

pnpm add @harmo-ui/css @harmo-ui/react

yarn add @harmo-ui/css @harmo-ui/react

bunx harmo-ui add switch

npx harmo-ui add switch

pnpm dlx harmo-ui add switch

yarn dlx harmo-ui add switch

Usage

import { Field, Switch } from "@harmo-ui/react";

<Field orientation="horizontal" label="Play a sound for new messages">
  <Switch defaultChecked />
</Field>

Examples

This site is using your theme

Off and on

A checkbox with role="switch", for a setting that applies at once. Screen readers announce it as a switch, and Space toggles it.

Set me as away

Play a sound for new messages

<>
  <Field orientation="horizontal" label="Set me as away">
    <Switch />
  </Field>
  <Field orientation="horizontal" label="Play a sound for new messages">
    <Switch defaultChecked />
  </Field>
</>

<div class="hfield" data-orientation="horizontal">
  <input class="hswitch" type="checkbox" role="switch" id="away" />
  <label class="hlabel" for="away">Set me as away</label>
</div>
<div class="hfield" data-orientation="horizontal">
  <input class="hswitch" type="checkbox" role="switch" id="message-sound" checked />
  <label class="hlabel" for="message-sound">Play a sound for new messages</label>
</div>

Disabled

disabled dims the switch, and its label turns gray.

Translate incoming messages

Two-factor sign-in, required by your administrator

<>
  <Field orientation="horizontal" label="Translate incoming messages">
    <Switch disabled />
  </Field>
  <Field
    orientation="horizontal"
    label="Two-factor sign-in, required by your administrator"
  >
    <Switch defaultChecked disabled />
  </Field>
</>

<div class="hfield" data-orientation="horizontal">
  <input class="hswitch" type="checkbox" role="switch" id="auto-translate" disabled />
  <label class="hlabel" for="auto-translate">Translate incoming messages</label>
</div>
<div class="hfield" data-orientation="horizontal">
  <input class="hswitch" type="checkbox" role="switch" id="two-factor" checked disabled />
  <label class="hlabel" for="two-factor">Two-factor sign-in, required by your administrator</label>
</div>

With a description

.hfield-content holds the label and a description; the switch stays centered on the label's first line.

Send read receipts

Customers see when you've read their messages.

<Field
  orientation="horizontal"
  label="Send read receipts"
  description="Customers see when you've read their messages."
>
  <Switch defaultChecked />
</Field>

<div class="hfield" data-orientation="horizontal">
  <input
    class="hswitch"
    type="checkbox"
    role="switch"
    id="read-receipts"
    aria-describedby="read-receipts-description"
    checked
  />
  <div class="hfield-content">
    <label class="hlabel" for="read-receipts">Send read receipts</label>
    <p class="hdescription" id="read-receipts-description">
      Customers see when you've read their messages.
    </p>
  </div>
</div>

Right to left

The same switches in Arabic: the thumb travels toward the end of the line, so on is at the left.

تعيين حالتي كغائب

تشغيل صوت للرسائل الجديدة

<>
  <Field orientation="horizontal" label="تعيين حالتي كغائب">
    <Switch />
  </Field>
  <Field orientation="horizontal" label="تشغيل صوت للرسائل الجديدة">
    <Switch defaultChecked />
  </Field>
</>

<div class="hfield" data-orientation="horizontal">
  <input class="hswitch" type="checkbox" role="switch" id="away-ar" />
  <label class="hlabel" for="away-ar">تعيين حالتي كغائب</label>
</div>
<div class="hfield" data-orientation="horizontal">
  <input class="hswitch" type="checkbox" role="switch" id="message-sound-ar" checked />
  <label class="hlabel" for="message-sound-ar">تشغيل صوت للرسائل الجديدة</label>
</div>

Custom size

--harmo-switch-height, --hswitch-width, and --hswitch-thumb resize the track and thumb; here 36×20 with a 16px thumb.

Compact conversation list

<Field orientation="horizontal" label="Compact conversation list">
  <Switch
    style={
      {
        "--harmo-switch-height": "20px",
        "--hswitch-width": "36px",
        "--hswitch-thumb": "16px",
      } as CSSProperties
    }
    defaultChecked
  />
</Field>

<div class="hfield" data-orientation="horizontal">
  <input
    class="hswitch"
    type="checkbox"
    role="switch"
    id="compact-view"
    style="--harmo-switch-height: 20px; --hswitch-width: 36px; --hswitch-thumb: 16px"
    checked
  />
  <label class="hlabel" for="compact-view">Compact conversation list</label>
</div>

API reference

React

<Switch> renders the <input type="checkbox" role="switch">. Put it in a horizontal Field for its label and description, or in a Setting. Its props are the input's attributes, such as checked, defaultChecked, and onChange.

HTML

An <input class="hswitch" type="checkbox" role="switch">, named by a <label for> or aria-labelledby. The input is the track and its ::before the thumb. Load switch.css; field.css for its label. It needs no script.

Hook	Effect
`checked`	On
`disabled`	Dimmed; the Field label turns gray
`--hswitch-width`, `--hswitch-thumb`, `--hswitch-inset` on the input	Track width (44px), thumb size (20px), and the thumb's inset (2px)
`--harmo-switch-height`	Track height (24px); a horizontal Field centers the switch by it

See Switch's full contract.

Accessibility

A native checkbox with role="switch": screen readers announce "switch, on" or "off", and Space toggles it. Its <label> names it, or in a Settings list the setting's title through aria-labelledby.