checkbox

A single checkbox with a caption.

{
  fields: [
    { name: 'agree', kind: 'checkbox', label: 'Send me release notes' },
    {
      name: 'terms',
      kind: 'checkbox',
      label: html('I accept the <a href="#" onclick="return false">terms</a>'),
    },
  ],
}

Rendered form

Values

—

Note that the value is a real boolean, and that the second caption is wrapped in html() so that its link is rendered as markup.

Options

Option	Type	Notes
label	TextOrHtml	Required. The caption beside the box

Plus everything in the shared options.

label vs. displayName

These are two different things, and a checkbox can have both:

• label is the caption next to the box: the thing the user agrees to.
• displayName is the label above the field, as on any other field.

{
  name: 'terms',
  displayName: 'Legal',                       // heading above
  kind: 'checkbox',
  label: 'I accept the terms of service',     // beside the box
}

Links inside the caption

Captions are rendered as plain text by default. If a caption contains a link, mark it as HTML yourself:

import { html } from 'declarative-forms';

{
  name: 'terms',
  kind: 'checkbox',
  label: html('I accept the <a href="/terms">terms of service</a>'),
}

See Text & HTML safety for why you have to ask for HTML.

Values

The value is a real boolean, not a string:

form.getValues()['agree']; // false

With defaultValue: true the box starts out checked. The string 'false' is treated as unchecked, which helps when values are stored as text and read back later.

Accessibility note

The caption is correctly connected to the input, so clicking it checks and unchecks the box, and under the default stylesheet the input is a real focusable control.

In classic.css it is not: the input is visibility: hidden and the visible box is drawn by a CSS pseudo-element, which takes it out of the keyboard tab order. See Accessibility. If you are staying on the classic look and need keyboard operation, use cards or a select with two options instead.