UnflowUI
Components

Switch

A binary toggle input rendered as a native checkbox styled to look like a sliding switch, with an optional label row.

Overview

Switch wraps a native <input type="checkbox"> with a custom CSS design. Because it is a real checkbox, it participates in forms, supports keyboard navigation natively, and works with standard React state patterns.

Two implementation notes worth knowing:

  • className applies directly to the <input> element, not a wrapper div — be precise with your overrides.
  • readOnly uses pointer-events-none + aria-readonly, because the HTML readonly attribute does not stop a checkbox from toggling.

Import

import { Switch } from '@unflowio/ui/components/Switch';

Props

PropTypeDefaultDescription
checkedboolean—Controlled checked state
onChangeChangeEventHandler<HTMLInputElement>—Change handler
disabledbooleanfalseDisables interaction, sets aria-disabled and HTML disabled
readOnlybooleanfalsePrevents interaction via pointer-events-none and sets aria-readonly
readonlyboolean—Deprecated. Use readOnly
defaultCheckedboolean—Uncontrolled initial value
labelReactNode—Text beside the control. Renders a label row whose whole area toggles the switch
descriptionReactNode—Secondary text under the label, announced as the accessible description. Needs label
labelPlacement'start' | 'end''end'Where the text sits. start puts the switch at the end of a full-width row
slotProps.rowBaseHTMLProps<HTMLLabelElement>—Props for the label row. Only rendered with label
slotProps.labelBaseHTMLProps<HTMLSpanElement>—Props for the label text
slotProps.descriptionBaseHTMLProps<HTMLSpanElement>—Props for the description text

All standard HTMLInputElement props are forwarded. Provide label or aria-label.

States

off
on
disabled off
disabled on
read-only
<Switch checked={false} onChange={setChecked} aria-label="Toggle feature" />
<Switch checked={true} onChange={setChecked} aria-label="Toggle feature" />
<Switch checked={false} disabled aria-label="Disabled off" />
<Switch checked={true} disabled aria-label="Disabled on" />
<Switch checked={true} readOnly aria-label="Read-only on" />

With a label

label renders the switch in a label row; clicking anywhere on the row toggles it. Add description for secondary text, and set labelPlacement="start" for settings lists where the switch sits at the end of the row. A read-only switch ignores clicks on the row too.

<Switch
  checked={sync}
  onChange={(e) => setSync(e.target.checked)}
  label="Sync across devices"
  description="Keeps your settings the same everywhere you sign in"
/>
<Switch
  checked={beta}
  onChange={(e) => setBeta(e.target.checked)}
  label="Beta features"
  labelPlacement="start"
/>
<Switch checked readOnly label="Single sign-on" description="Managed by your admin" />

Controlled usage

import { useState } from 'react';
import { Switch } from '@unflowio/ui/components/Switch';

function FeatureToggle() {
  const [enabled, setEnabled] = useState(false);

  return (
    <Switch
      checked={enabled}
      onChange={(e) => setEnabled(e.target.checked)}
      aria-label="Enable dark mode"
    />
  );
}

Uncontrolled usage

<Switch defaultChecked aria-label="Enable notifications" />

Read-only vs disabled

Both prevent the user from changing the value, but communicate different semantics:

  • disabled — the control is not available. Uses HTML disabled + aria-disabled="true". The value is excluded from form submission.
  • readOnly — the value is fixed but the control is present and accessible. Uses pointer-events-none + aria-readonly="true". The value is included in form submission.

Accessibility

  • Renders <input type="checkbox" role="switch"> — natively keyboard-operable (Space to toggle).
  • aria-checked mirrors the checked prop.
  • With label, the switch is named by the label text through aria-labelledby and described by description through aria-describedby.
  • A console warning fires in development when there is no label, aria-label or aria-labelledby.