checkbox

Custom-styled checkbox with animated check mark, full keyboard and screen-reader support. Pairs with fieldset for labelled groups.

Basic

Pass label for the visible text. The id is auto-generated from name and value.

I agree to the terms

checkbox({ name: 'agree', label: 'I agree to the terms' })

Checked

Send me updates

checkbox({ name: 'newsletter', label: 'Send me updates', checked: state.newsletter })

Hint

A hint string renders below the label as supporting copy.

Marketing emails

Product news and tips. Unsubscribe any time.

checkbox({
  name:    'marketing',
  label:   'Marketing emails',
  hint:    'Product news and tips. Unsubscribe any time.',
  checked: state.marketing,
})

Error state

Pass error to show a validation message. The error is announced via role="alert".

I accept the terms and conditions

You must accept the terms to continue.

checkbox({
  name:  'terms',
  label: 'I accept the terms and conditions',
  error: server.errors.terms,
})

Disabled

Enable beta features Beta feature (on)

checkbox({ name: 'feature', label: 'Enable beta features', disabled: true })

Group in a fieldset

Compose multiple checkboxes inside a fieldset for a semantic group.

Notifications

Email SMS Browser push Weekly digest

fieldset({
  legend:  'Notifications',
  content:
    checkbox({ name: 'notif', value: 'email',   label: 'Email',         checked: true }) +
    checkbox({ name: 'notif', value: 'sms',     label: 'SMS'                          }) +
    checkbox({ name: 'notif', value: 'browser', label: 'Browser push',  checked: true }) +
    checkbox({ name: 'notif', value: 'weekly',  label: 'Weekly digest', disabled: true }),
})

In forms

Checkboxes submit their value string (defaulting to "on") under name in FormData only when checked. Unchecked checkboxes are absent from FormData. Read them in action.onStart via formData.get('agree') — a null result means unchecked.

Custom label HTML

When the label needs inline styling — for example a strikethrough on a completed todo — use labelHtml instead of label. The value is inserted as raw HTML so you are responsible for escaping any user content.

Buy milk

checkbox({
  name:      'task',
  checked:   todo.done,
  labelHtml: `<span class="${todo.done ? 'u-text-muted' : ''}">${esc(todo.text)}</span>`,
})

Props

Prop	Type	Default
`name`	string	—	Field name
`value`	string	—	Submitted value when checked (defaults to browser default `"on"`)
`label`	string	—	Visible label text — escaped
`labelHtml`	string	—	Raw HTML label slot — not escaped, use for styled spans
`checked`	boolean	false
`disabled`	boolean	false
`id`	string	—	Override the auto-generated `id`
`event`	string	—	`data-event` binding, e.g. `"change:toggle"`
`hint`	string	—	Helper text below the label
`error`	string	—	Validation error — announced via `role="alert"`
`class`	string	—