Switch

Turns a setting on or off straight away, with no Save button.

SourcePackage @kerf-js/veneerTry it

Preview

tsx

import { state } from '@kerf-js/core'import { Switch } from '@kerf-js/veneer'export function Basic() {  const on = state(true)  return (    <Switch      checked={on.value}      onChange={(        e: Event & { currentTarget: HTMLInputElement },      ) => (on.value = e.currentTarget.checked)}    >      Preview deploys    </Switch>  )}

Installation

npm install @kerf-js/veneer

Try it

Change the controls: the preview and its code update together. The address keeps what you set, so you can link to it.

Live preview

Controls

Label

Hint

Checked

Size

smmd

Size

Placement

endstart

Placement

Disabled

Codeupdates as you change the controls

import { Switch } from '@kerf-js/veneer'<Switch checked>Preview deploys</Switch>

Usage

tsx

import { Switch } from '@kerf-js/veneer'<Switch>Preview deploys</Switch>

Placement

placement picks the side the switch sits on.

tsx

import { Stack, Switch } from '@kerf-js/veneer'export function Placement() {  return (  <Stack gap="related">    <Switch checked>Preview deploys</Switch>    <Switch      checked      placement="start"    >      Preview deploys    </Switch>  </Stack>  )}

Sizes

Use size to pick sm or md.

tsx

import { Stack, Switch } from '@kerf-js/veneer'export function Sizes() {  return (  <Stack gap="related">    <Switch      size="sm"      checked    >      Preview deploys    </Switch>    <Switch checked>Preview deploys</Switch>  </Stack>  )}

With a hint

A switch's hint is a quieter second line under its label.

tsx

import { Switch } from '@kerf-js/veneer'export function Hint() {  return (  <Switch    checked    hint="Every pull request gets its own address."  >    Preview deploys  </Switch>  )}

States

A switch can be on or off, show a hint, or be disabled either way.

tsx

import { Grid, Switch } from '@kerf-js/veneer'import { Stack, Text } from '@kerf-js/veneer'export function States() {  return (  <Grid    cols={3}    gap="group"  >    <Cell name="Off">      <Switch>Preview deploys</Switch>    </Cell>    <Cell name="On">      <Switch checked>Preview deploys</Switch>    </Cell>    <Cell name="Hint">      <Switch hint={previewHint}>Preview deploys</Switch>    </Cell>    <Cell name="Disabled off">      <Switch disabled>Preview deploys</Switch>    </Cell>    <Cell name="Disabled on">      <Switch        checked        disabled      >        Preview deploys      </Switch>    </Cell>  </Grid>  )}const Cell = ({  name,  children,}: {  name: string  children?: unknown}) => (  <Stack gap="tight">    <Text      role="caption"      subtle    >      {name}    </Text>    {children}  </Stack>)const previewHint =  'Every pull request gets its own address.'

Settings that apply at once

Each flip takes effect and says so.

tsx

import { state } from '@kerf-js/core'import {  Stack,  Switch,  Toaster,  toast} from '@kerf-js/veneer'export function Settings() {  const previews = state(true)  const analytics = state(false)  const paused = state(false)  const say = (title: string, on: boolean) =>    toast.show({ title: `${title} ${on ? 'on' : 'off'}` })  return (    <Stack      gap="group"      divided    >      <Switch        checked={previews.value}        hint={previewHint}        onChange={(          e: Event & { currentTarget: HTMLInputElement },        ) =>          say(            'Preview deploys',            (previews.value = e.currentTarget.checked),          )        }      >        Preview deploys      </Switch>      <Switch        checked={analytics.value}        hint="Adds about 1 KB to each page."        onChange={(          e: Event & { currentTarget: HTMLInputElement },        ) =>          say(            'Web analytics',            (analytics.value = e.currentTarget.checked),          )        }      >        Web analytics      </Switch>      <Switch        checked={paused.value}        hint={pauseHint}        onChange={(          e: Event & { currentTarget: HTMLInputElement },        ) =>          say(            'Pause',            (paused.value = e.currentTarget.checked),          )        }      >        Pause project      </Switch>      <Toaster />    </Stack>  )}const previewHint =  'Every pull request gets its own address.'const pauseHint =  'Takes the project offline until you switch it back.'

When to use

Use it for

A setting that applies the moment it's flipped

Reach for something else

Checkbox, when it waits for a Save button
Toggle, when it's a tool in a toolbar

Accessibility

Space: Toggles

A real checkbox with the switch role, so it reads as on or off.
Keep the label the same in both states. Say what it controls, not what it's doing.

API Reference

Prop	Type	Default	Description
`checked`	`boolean`	`false`	Whether it is on. You own this value.
`hint`	`unknown`	—	A short line under the label.
`size`	`"sm" \| "md"`	—	`sm` or `md`.
`placement`	`"start" \| "end"`	`'end'`	Which side of the label the switch sits on.
`children`	`unknown`	—	What it contains.

Parts

Every element carries a stable name, so you can style it from your own CSS: [data-scope="switch"] [data-part="track"]

trackrail-fillrail-hoverthumblabelhint

RelatedCheckbox Toggle