Checkbox

A yes or no that takes effect when the form is saved.

SourcePackage @weft-js/warpPlayground

Preview

tsx

import { state } from '@weft-js/core'import { Checkbox } from '@weft-js/warp'export function Basic() {  const on = state(true)  return <Checkbox checked={on.value} onChange={(e: Event & { currentTarget: HTMLInputElement }) => (on.value = e.currentTarget.checked)}>Deploy on push</Checkbox>}

Installation

npm install @weft-js/warp

Usage

tsx

import { Checkbox } from '@weft-js/warp'<Checkbox>Deploy on push</Checkbox>

With a hint

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

tsx

import { state } from '@weft-js/core'import { Checkbox } from '@weft-js/warp'export function Hint() {  const on = state(false)  return <Checkbox checked={on.value} hint="Failed checks stop the deploy." onChange={(e: Event & { currentTarget: HTMLInputElement }) => (on.value = e.currentTarget.checked)}>Require checks to pass</Checkbox>}

States

A checkbox can be checked, indeterminate or disabled, and can show a hint or an error.

tsx

import { Checkbox, Grid, Stack, Text } from '@weft-js/warp'export function States() {  return (    <Grid cols={3} gap="group">      <Cell name="Off"><Checkbox>Deploy on push</Checkbox></Cell>      <Cell name="On"><Checkbox checked>Deploy on push</Checkbox></Cell>      <Cell name="Part of a set"><Checkbox indeterminate>Deploy on push</Checkbox></Cell>      <Cell name="Hint"><Checkbox hint="Every push to main goes live.">Deploy on push</Checkbox></Cell>      <Cell name="Invalid"><Checkbox error="Accept this to carry on.">Deploy on push</Checkbox></Cell>      <Cell name="Disabled"><Checkbox checked disabled>Deploy on push</Checkbox></Cell>    </Grid>  )}const Cell = (p: { name: string; children?: unknown }) => (  <Stack gap="tight">    <Text role="caption" subtle>{p.name}</Text>    {p.children}  </Stack>)

Select all

The parent shows a dash while only some are on.

tsx

import { derived, state } from '@weft-js/core'import { Checkbox, Stack } from '@weft-js/warp'export function SelectAll() {  const on = state(['Deploy failed', 'Uptime drops'])  const flip = (name: string) => (on.value = on.value.includes(name) ? on.value.filter(n => n !== name) : [...on.value, name])  const all = derived(() => on.value.length === EVENTS.length)  return (    <Stack gap="tight">      <Checkbox checked={all.value} indeterminate={on.value.length > 0 && !all.value} onChange={() => (on.value = all.value ? [] : EVENTS)}>Email me about</Checkbox>      <Stack gap="tight" style="padding-inline-start:var(--warp-space-group)">        {EVENTS.map(name => <Checkbox key={name} checked={on.value.includes(name)} onChange={() => flip(name)}>{name}</Checkbox>)}      </Stack>    </Stack>  )}const EVENTS = ['Deploy failed', 'Deploy finished', 'Uptime drops', 'Budget reached']

Confirm before deleting

Press Delete without ticking it.

tsx

import { state } from '@weft-js/core'import { Button, Checkbox, Row, Stack, Text } from '@weft-js/warp'export function Confirm() {  const sure = state(false)  const tried = state(false)  const gone = state(false)  const remove = () => {    tried.value = true    if (sure.value) gone.value = true  }  return (    <Stack gap="group">      <Text>{gone.value ? 'reports was deleted.' : 'Deleting reports removes its 41 deploys and all its logs.'}</Text>      <Checkbox checked={sure.value} error={tried.value && !sure.value ? 'Tick this first.' : undefined} onChange={(e: Event & { currentTarget: HTMLInputElement }) => (sure.value = e.currentTarget.checked)}>I understand this can't be undone</Checkbox>      <Row justify="end"><Button tone="critical" onClick={remove}>Delete project</Button></Row>    </Stack>  )}

When to use

Use it for

An option inside a form with a Save button
Picking any number from a list

Reach for something else

Switch, when it applies straight away
RadioGroup, when exactly one can be chosen

Playground

Label

Hint

Checked

Indeterminate

Disabled

import { Checkbox } from '@weft-js/warp'<Checkbox checked>Deploy on push</Checkbox>

Accessibility

Space: Toggles

It is a real checkbox, and the whole label can be pressed.
indeterminate sets the real property, so it is announced as mixed.

API Reference

Prop	Type	Default	Description
`checked`	`boolean`	`false`	Whether it is on. You own this value.
`indeterminate`	`boolean`	`false`	Shows a dash: some of a set are on.
`hint`	`unknown`	—	A short line under the label.
`error`	`unknown`	—	Replaces the hint and marks it invalid.
`children`	`unknown`	—	What it contains.

Parts

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

controlcheckdashlabelhint

RelatedSwitch Radio group Chip