Skip to content

Field

A labeled input, textarea, checkbox, radio or group, with help and an error, checked on leave.

<div class="cap-field">
  <label class="cap-field-label" for="f-default">Site name</label>
  <input class="cap-input" id="f-default" autocomplete="off" />
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/field.css";
import { enhance } from "capsomer/behavior/field";

enhance();

Usage

<form data-cap="field">
  <div class="cap-field">
    <label class="cap-field-label" for="url">Site address <span class="cap-field-required" aria-hidden="true">Required</span></label>
    <p class="cap-field-help" id="url-h">Starts with https:// and has no path.</p>
    <input class="cap-input" id="url" type="url" required aria-describedby="url-e url-h"
      data-error-type-mismatch="Enter a full address, starting with https://." />
    <p class="cap-field-error" id="url-e" hidden></p>
  </div>
  <fieldset class="cap-field">
    <legend class="cap-field-label">Check every</legend>
    <div class="cap-field-options">
      <label class="cap-check"><input type="radio" name="every" value="5" checked /> 5 minutes</label>
      <label class="cap-check"><input type="radio" name="every" value="15" /> 15 minutes</label>
    </div>
  </fieldset>
  <label class="cap-check"><input type="checkbox" name="watch" /> Watch this site</label>
  <button type="submit" class="cap-btn" data-variant="primary">Add site</button>
</form>
<div class="cap-field">
  <label class="cap-field-label" for="pw">Password</label>
  <div class="cap-input-group">
    <input class="cap-input" id="pw" name="password" type="password" autocomplete="current-password" spellcheck="false" autocapitalize="none" />
    <div class="cap-input-addon" data-align="inline-end">
      <button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-cap-part="reveal" aria-controls="pw" aria-label="Show password" hidden>Show</button>
    </div>
  </div>
</div>

<div class="cap-field">
  <label class="cap-field-label" for="sum">Summary</label>
  <textarea class="cap-input" id="sum" name="summary" data-maxlength="120" aria-describedby="sum-c"></textarea>
  <p class="cap-field-count" id="sum-c">You can enter up to 120 characters</p>
  <p class="cap-field-error" hidden></p>
</div>

<input class="cap-input" data-variant="code" id="code" name="code" autocomplete="one-time-code" inputmode="numeric" spellcheck="false" />

<div class="cap-input-group">
  <div class="cap-input-addon" data-align="inline-start"><button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-icon-only data-cap-part="step-down" tabindex="-1" aria-label="Decrease retries" hidden>&minus;</button></div>
  <input class="cap-input" id="retries" name="retries" type="number" min="0" max="10" value="3" />
  <div class="cap-input-addon" data-align="inline-end"><button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-icon-only data-cap-part="step-up" tabindex="-1" aria-label="Increase retries" hidden>+</button></div>
</div>

<form class="cap-search" role="search" aria-label="Posts" action="/search">
  <div class="cap-field">
    <label class="cap-field-label" for="q">Search posts</label>
    <div class="cap-input-group">
      <div class="cap-input-addon" data-align="inline-start">[search icon]</div>
      <input class="cap-input" id="q" name="q" type="search" enterkeyhint="search" />
      <div class="cap-input-addon" data-align="inline-end"><button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-icon-only data-cap-part="clear" aria-label="Clear search" hidden>[x icon]</button></div>
    </div>
  </div>
</form>

<fieldset class="cap-field" aria-describedby="dob-h">
  <legend class="cap-field-label">Date of birth</legend>
  <p class="cap-field-help" id="dob-h">For example, 27 3 1990.</p>
  <div class="cap-date-input" data-error-date="Date of birth must be a real date.">
    <div class="cap-date-input-part"><label for="dob-d">Day</label><input class="cap-input" id="dob-d" name="dob-day" data-cap-part="day" inputmode="numeric" pattern="[0-9]{1,2}" autocomplete="bday-day" /></div>
    <div class="cap-date-input-part"><label for="dob-m">Month</label><input class="cap-input" id="dob-m" name="dob-month" data-cap-part="month" inputmode="numeric" pattern="[0-9]{1,2}" autocomplete="bday-month" /></div>
    <div class="cap-date-input-part"><label for="dob-y">Year</label><input class="cap-input" id="dob-y" name="dob-year" data-cap-part="year" inputmode="numeric" pattern="[0-9]{4}" autocomplete="bday-year" /></div>
  </div>
  <p class="cap-field-error" hidden></p>
</fieldset>
<Field label="Site address" help="Starts with https:// and has no path." error={errors.url} announce={submitted} required>
  <input className="cap-input" type="url" value={url} onChange={(e) => setUrl(e.target.value)} />
</Field>
<PasswordInput label="Password" autoComplete="current-password" name="password" />
<CharacterCount label="Summary" limit={120} value={summary} onChange={(e) => setSummary(e.target.value)} />
<NumberField label="Retries" min={0} max={10} value={retries} onChange={setRetries} />
<SearchField label="Search posts" landmark="Posts" action="/search" value={q} onChange={setQ} />
<DateInput legend="Date of birth" name="dob" autoComplete="bday" value={dob} onChange={setDob} error={errors.dob} invalid={["month"]} />
<div class="cap-input-group" role="group" aria-label="Site address">
  <div class="cap-input-addon" data-align="inline-start"><span class="cap-input-group-text">https://</span></div>
  <input class="cap-input" id="u" />
  <div class="cap-input-addon" data-align="inline-end"><button type="button" class="cap-btn" data-size="xs" data-variant="quiet">Paste</button></div>
</div>
<label class="cap-check" data-variant="card"><input type="radio" name="plan" checked /> <span>Free</span></label>
<div class="cap-field" data-orientation="horizontal">...</div>
<div class="cap-field-group">...fields, with .cap-field-separator between groups...</div>

Examples

Keyboard focus and hover

<p class="cap-muted">Tab into the first field to see focus. The second is shown hovered.</p>
<div class="cap-field">
  <label class="cap-field-label" for="f-focus">Branch</label>
  <input class="cap-input" id="f-focus" autocomplete="off" />
</div>
<div class="cap-field">
  <label class="cap-field-label" for="f-hover">Tag</label>
  <input class="cap-input" id="f-hover" autocomplete="off" />
</div>

Filled, with a placeholder example

<div class="cap-field">
  <label class="cap-field-label" for="f-filled">Site name</label>
  <input class="cap-input" id="f-filled" value="Example Co" autocomplete="off" />
</div>
<div class="cap-field">
  <label class="cap-field-label" for="f-placeholder">Owner</label>
  <input class="cap-input" id="f-placeholder" placeholder="For example: capsid-driver" autocomplete="off" />
</div>

Help text and required

<div class="cap-field">
  <label class="cap-field-label" for="f-help">Site address <span class="cap-field-required" aria-hidden="true">Required</span></label>
  <p class="cap-field-help" id="f-help-h">Starts with https:// and has no path.</p>
  <input class="cap-input" id="f-help" type="url" required aria-describedby="f-help-h" autocomplete="off" />
</div>
<div class="cap-field">
  <label class="cap-field-label" for="f-notes">Notes</label>
  <p class="cap-field-help" id="f-notes-h">Shown to anyone who opens the site's page.</p>
  <textarea class="cap-input" id="f-notes" aria-describedby="f-notes-h">Moved to Cloudflare on September 12.</textarea>
</div>

Invalid, with its message

<div class="cap-field">
  <label class="cap-field-label" for="f-invalid">Site address</label>
  <p class="cap-field-help" id="f-invalid-h">Starts with https:// and has no path.</p>
  <input class="cap-input" id="f-invalid" type="url" value="http://example.com/health" aria-invalid="true" aria-describedby="f-invalid-e f-invalid-h" autocomplete="off" />
  <p class="cap-field-error" id="f-invalid-e">Use https:// and remove "/health". The health route has its own field.</p>
</div>

Disabled and read-only

<div class="cap-field">
  <label class="cap-field-label" for="f-disabled">Platform</label>
  <p class="cap-field-help" id="f-disabled-h">Set by the deploy. Change it in the repository.</p>
  <input class="cap-input" id="f-disabled" value="Cloudflare" disabled aria-describedby="f-disabled-h" />
</div>
<div class="cap-field">
  <label class="cap-field-label" for="f-readonly">Site id</label>
  <input class="cap-input cap-mono" id="f-readonly" value="site_7f3a91c2" readonly />
</div>

Checkbox and radio, checked and unchecked

<div class="cap-field-options">
  <label class="cap-check"><input type="checkbox" id="c-on" checked /> Watch this site</label>
  <label class="cap-check"><input type="checkbox" id="c-off" /> Email me when it goes down</label>
  <label class="cap-check"><input type="checkbox" disabled /> Post to the status page (not set up)</label>
</div>
<fieldset class="cap-field">
  <legend class="cap-field-label">Check every</legend>
  <div class="cap-field-options">
    <label class="cap-check"><input type="radio" name="every" value="1" /> 1 minute</label>
    <label class="cap-check"><input type="radio" name="every" value="5" checked /> 5 minutes</label>
    <label class="cap-check"><input type="radio" name="every" value="15" /> 15 minutes</label>
  </div>
</fieldset>

Checkbox and radio, every state

<div class="cap-specimen-row">
  <label class="cap-check"><input type="checkbox" id="c-mixed" data-indeterminate /> Select all sites (some chosen)</label>
  <label class="cap-check"><input type="checkbox" id="c-hover" /> Hovered</label>
  <label class="cap-check"><input type="checkbox" id="c-invalid" aria-invalid="true" aria-describedby="c-invalid-e" /> Accept the terms</label>
  <label class="cap-check"><input type="checkbox" id="c-disabled-on" checked disabled /> Disabled and checked</label>
  <label class="cap-check"><input type="radio" name="r-state" id="r-invalid" aria-invalid="true" /> A radio in error</label>
  <label class="cap-check"><input type="radio" name="r-state2" id="r-on" checked /> A radio chosen</label>
  <label class="cap-check"><input type="radio" name="r-state3" disabled /> A radio disabled</label>
</div>
<p class="cap-field-error" id="c-invalid-e">Accept the terms to continue.</p>

Text, file and textarea in error

<div class="cap-field">
  <label class="cap-field-label" for="f-file">Import sites</label>
  <input class="cap-input" id="f-file" type="file" />
</div>
<div class="cap-field" data-invalid="true">
  <label class="cap-field-label" for="f-tarea-bad">Notes</label>
  <textarea class="cap-input" id="f-tarea-bad" aria-invalid="true" aria-describedby="f-tarea-bad-e">x</textarea>
  <p class="cap-field-error" id="f-tarea-bad-e">Write at least 20 characters, for example what changed.</p>
</div>

Input group

<div class="cap-field">
  <label class="cap-field-label" for="g-url">Site address</label>
  <div class="cap-input-group" role="group" aria-label="Site address with scheme">
    <div class="cap-input-addon" data-align="inline-start"><span class="cap-input-group-text">https://</span></div>
    <input class="cap-input" id="g-url" autocomplete="off" />
    <div class="cap-input-addon" data-align="inline-end">
      <button type="button" class="cap-btn" data-size="xs" data-variant="quiet" aria-label="Paste an address">Paste</button>
    </div>
  </div>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="g-bad">Search sites</label>
  <div class="cap-input-group" role="group" aria-label="Search sites">
    <div class="cap-input-addon" data-align="inline-start">
      <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="7" cy="7" r="4.5" fill="none" stroke="currentColor" stroke-width="1.5" /><path d="M10.5 10.5L14 14" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg>
    </div>
    <input class="cap-input" id="g-bad" aria-invalid="true" aria-describedby="g-bad-e" value="***" />
  </div>
  <p class="cap-field-error" id="g-bad-e">Use letters and numbers.</p>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="g-off">Owner</label>
  <div class="cap-input-group" role="group" aria-label="Owner">
    <input class="cap-input" id="g-off" value="capsid-driver" disabled />
  </div>
</div>

Choice cards and a horizontal field

<fieldset class="cap-field">
  <legend class="cap-field-label">Plan</legend>
  <label class="cap-check" data-variant="card" id="card-on"><input type="radio" name="plan" value="free" checked /> <span>Free<br /><span class="cap-field-description">Five sites, daily checks.</span></span></label>
  <label class="cap-check" data-variant="card"><input type="radio" name="plan" value="team" /> <span>Team<br /><span class="cap-field-description">Unlimited sites, one-minute checks.</span></span></label>
</fieldset>
<div class="cap-field" data-orientation="horizontal">
  <div class="cap-field-content">
    <label class="cap-check" for="h-watch"><input type="checkbox" id="h-watch" aria-describedby="h-watch-d" /> Watch this site</label>
    <p class="cap-field-description" id="h-watch-d">Get an email when it goes down.</p>
  </div>
</div>

Comfortable density

<div class="cap-specimen-row" data-density="comfortable" id="f-comfortable">
  <div class="cap-field">
    <label class="cap-field-label" for="f-comf">Site name</label>
    <input class="cap-input" id="f-comf" value="Example Co" autocomplete="off" />
  </div>
  <label class="cap-check"><input type="checkbox" checked /> Watch this site</label>
  <label class="cap-check"><input type="radio" name="comf" checked /> Daily</label>
</div>

A live form

<form class="cap-field-options" id="add-site" data-cap="field" action="#added" aria-labelledby="s-live">
  <div class="cap-field">
    <label class="cap-field-label" for="site-name">Site name <span class="cap-field-required" aria-hidden="true">Required</span></label>
    <input class="cap-input" id="site-name" name="name" required autocomplete="off" aria-describedby="site-name-e" data-error-value-missing="Give the site a name, such as Field notes." />
    <p class="cap-field-error" id="site-name-e" hidden></p>
  </div>
  <div class="cap-field">
    <label class="cap-field-label" for="site-url">Site address <span class="cap-field-required" aria-hidden="true">Required</span></label>
    <p class="cap-field-help" id="site-url-h">Starts with https:// and has no path.</p>
    <input
      class="cap-input"
      id="site-url"
      name="url"
      type="url"
      required
      pattern="https://[^\/\s]+\/?"
      autocomplete="off"
      aria-describedby="site-url-e site-url-h"
      data-error-value-missing="Enter the site's address."
      data-error-type-mismatch="Enter a full address, starting with https://."
      data-error-pattern-mismatch="Use https:// and leave off any path, such as /health."
    />
    <p class="cap-field-error" id="site-url-e" hidden></p>
  </div>
  <fieldset class="cap-field">
    <legend class="cap-field-label">Platform <span class="cap-field-required" aria-hidden="true">Required</span></legend>
    <div class="cap-field-options">
      <label class="cap-check"><input type="radio" name="platform" value="cloudflare" required aria-describedby="platform-e" data-error-value-missing="Choose where the site runs." /> Cloudflare</label>
      <label class="cap-check"><input type="radio" name="platform" value="vercel" aria-describedby="platform-e" /> Vercel</label>
    </div>
    <p class="cap-field-error" id="platform-e" hidden></p>
  </fieldset>
  <label class="cap-check"><input type="checkbox" name="watch" id="live-watch" /> Start checks on the next pass</label>
  <div><button type="submit" class="cap-btn" data-variant="primary">Add site</button></div>
  <p class="cap-muted" id="add-result" role="status"></p>
</form>

Slider, at rest and under the pointer

<div class="cap-field">
  <label class="cap-field-label" for="range-mrr">Monthly budget</label>
  <input class="cap-range" id="range-mrr" type="range" min="1000" max="500000" step="1000" value="25000" style="--cap-range-fill: 4.81%" />
</div>
<div class="cap-field">
  <label class="cap-field-label" for="range-share">Share of the budget spent</label>
  <input class="cap-range" id="range-share" type="range" min="0" max="100" value="52" style="--cap-range-fill: 52%" />
</div>

Slider with its readout and the words at its ends

<div class="cap-field">
  <label class="cap-field-label" for="rf-mrr"><span class="cap-range-field-head">Monthly revenue <span class="cap-range-field-value" aria-hidden="true">$25,000</span></span></label>
  <input class="cap-range" id="rf-mrr" type="range" min="1000" max="500000" step="1000" value="25000" aria-valuetext="$25,000" />
  <div class="cap-range-field-ends" aria-hidden="true"><span>$1,000</span><span>$500,000</span></div>
</div>

A span from two menus

<fieldset class="cap-field">
  <legend class="cap-field-label">Years</legend>
  <div class="cap-span-field-ends">
    <div class="cap-span-field-end">
      <label for="span-from">From</label>
      <select class="cap-select" id="span-from" name="from"><option value="">Any</option><option value="2019" selected>2019</option><option value="2020">2020</option><option value="2024">2024</option></select>
    </div>
    <div class="cap-span-field-end">
      <label for="span-to">To</label>
      <select class="cap-select" id="span-to" name="to"><option value="" selected>Any</option><option value="2019">2019</option><option value="2020">2020</option><option value="2024">2024</option></select>
    </div>
  </div>
</fieldset>

A field with its action, help under the control, and money

<div class="cap-field">
  <label class="cap-field-label" for="fa-invite">Invite by email</label>
  <div class="cap-field-row">
    <input class="cap-input" id="fa-invite" type="email" autocomplete="off" aria-describedby="fa-invite-help" />
    <button type="button" class="cap-btn">Send invite</button>
  </div>
  <p class="cap-field-help" id="fa-invite-help">They get a link that works for seven days.</p>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="fa-fee">Registration fee</label>
  <div class="cap-input-group">
    <div class="cap-input-addon" data-align="inline-start"><span class="cap-input-group-text" aria-hidden="true">lt;/span></div>
    <input class="cap-input" id="fa-fee" type="text" inputmode="decimal" autocomplete="off" value="25" />
  </div>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="fa-opens">Registration opens</label>
  <p class="cap-field-help" id="fa-opens-help">In America/Chicago.</p>
  <input class="cap-input" id="fa-opens" type="datetime-local" value="2026-12-01T09:00" aria-describedby="fa-opens-help" />
</div>

Password with Show and Hide

<div class="cap-field">
  <label class="cap-field-label" for="pw-current">Password</label>
  <div class="cap-input-group">
    <input class="cap-input" id="pw-current" name="password" type="password" autocomplete="current-password" spellcheck="false" autocapitalize="none" value="spring-field-day" />
    <div class="cap-input-addon" data-align="inline-end">
      <button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-cap-part="reveal" aria-controls="pw-current" aria-label="Show password" hidden>Show</button>
    </div>
  </div>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="pw-new">New password</label>
  <p class="cap-field-help" id="pw-new-h">At least 12 characters. Four words you will remember are enough.</p>
  <div class="cap-input-group">
    <input class="cap-input" id="pw-new" name="new-password" type="password" autocomplete="new-password" minlength="12" spellcheck="false" autocapitalize="none" aria-describedby="pw-new-h" />
    <div class="cap-input-addon" data-align="inline-end">
      <button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-cap-part="reveal" aria-controls="pw-new" aria-label="Show password" hidden>Show</button>
    </div>
  </div>
</div>

One-time code

<div class="cap-field">
  <label class="cap-field-label" for="otp">Sign-in code</label>
  <p class="cap-field-help" id="otp-h">The 6 digits in the email we sent you. You can paste it.</p>
  <input class="cap-input" data-variant="code" id="otp" name="code" autocomplete="one-time-code" inputmode="numeric" spellcheck="false" aria-describedby="otp-h" />
</div>

Character count, under and over the limit

<div class="cap-field">
  <label class="cap-field-label" for="cc-summary">Summary</label>
  <p class="cap-field-help" id="cc-summary-h">Shown under the post's title in feeds.</p>
  <textarea class="cap-input" id="cc-summary" name="summary" data-maxlength="120" aria-describedby="cc-summary-c cc-summary-h">Notes from the September field day at the garden plot.</textarea>
  <p class="cap-field-count" id="cc-summary-c">You can enter up to 120 characters</p>
  <p class="cap-field-error" hidden></p>
</div>
<div class="cap-field">
  <label class="cap-field-label" for="cc-bio">Short bio</label>
  <textarea class="cap-input" id="cc-bio" name="bio" data-maxwords="12" aria-describedby="cc-bio-c">Volunteer who keeps field notes for the spring survey in two parks, and writes about the work.</textarea>
  <p class="cap-field-count" id="cc-bio-c">You can enter up to 12 words</p>
  <p class="cap-field-error" hidden></p>
</div>

Number with steppers

<div class="cap-field">
  <label class="cap-field-label" for="num-retries">Retries</label>
  <p class="cap-field-help" id="num-retries-h">From 0 to 10.</p>
  <div class="cap-input-group">
    <div class="cap-input-addon" data-align="inline-start">
      <button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-icon-only data-cap-part="step-down" tabindex="-1" aria-label="Decrease retries" hidden>&minus;</button>
    </div>
    <input class="cap-input" id="num-retries" name="retries" type="number" min="0" max="10" step="1" value="3" aria-describedby="num-retries-h" />
    <div class="cap-input-addon" data-align="inline-end">
      <button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-icon-only data-cap-part="step-up" tabindex="-1" aria-label="Increase retries" hidden>+</button>
    </div>
  </div>
</div>
<form class="cap-search" role="search" aria-label="Posts" action="#results">
  <div class="cap-field">
    <label class="cap-field-label" for="q-posts">Search posts</label>
    <div class="cap-input-group">
      <div class="cap-input-addon" data-align="inline-start">
        <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><circle cx="7" cy="7" r="4.5" fill="none" stroke="currentColor" stroke-width="1.5" /><path d="M10.5 10.5L14 14" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg>
      </div>
      <input class="cap-input" id="q-posts" name="q" type="search" enterkeyhint="search" value="field day" />
      <div class="cap-input-addon" data-align="inline-end">
        <button type="button" class="cap-btn" data-size="xs" data-variant="quiet" data-icon-only data-cap-part="clear" aria-label="Clear search" hidden>
          <svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true" focusable="false"><path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg>
        </button>
      </div>
    </div>
  </div>
</form>

Date input, and one part in error

<fieldset class="cap-field" aria-describedby="dob-h">
  <legend class="cap-field-label">Date of birth</legend>
  <p class="cap-field-help" id="dob-h">For example, 27 3 1990.</p>
  <div class="cap-date-input">
    <div class="cap-date-input-part"><label for="dob-day">Day</label><input class="cap-input" id="dob-day" name="dob-day" data-cap-part="day" inputmode="numeric" pattern="[0-9]{1,2}" autocomplete="bday-day" /></div>
    <div class="cap-date-input-part"><label for="dob-month">Month</label><input class="cap-input" id="dob-month" name="dob-month" data-cap-part="month" inputmode="numeric" pattern="[0-9]{1,2}" autocomplete="bday-month" /></div>
    <div class="cap-date-input-part"><label for="dob-year">Year</label><input class="cap-input" id="dob-year" name="dob-year" data-cap-part="year" inputmode="numeric" pattern="[0-9]{4}" autocomplete="bday-year" /></div>
  </div>
</fieldset>
<fieldset class="cap-field" data-invalid="true" aria-describedby="since-h">
  <legend class="cap-field-label">Member since</legend>
  <p class="cap-field-help" id="since-h">For example, 9 2024.</p>
  <div class="cap-date-input">
    <div class="cap-date-input-part"><label for="since-month">Month</label><input class="cap-input" id="since-month" data-cap-part="month" inputmode="numeric" value="13" aria-invalid="true" aria-describedby="since-e" autocomplete="off" /></div>
    <div class="cap-date-input-part"><label for="since-year">Year</label><input class="cap-input" id="since-year" data-cap-part="year" inputmode="numeric" value="2024" aria-describedby="since-e" autocomplete="off" /></div>
  </div>
  <p class="cap-field-error" id="since-e">Member since must have a month from 1 to 12.</p>
</fieldset>

A live sign-up form: one error, and a date that does not exist

<form class="cap-field-options" id="join" data-cap="field" action="#joined" aria-labelledby="s-join">
  <div class="cap-field">
    <label class="cap-field-label" for="join-email">Email</label>
    <input class="cap-input" id="join-email" name="email" type="email" autocomplete="email" spellcheck="false" value="maya.chen@example.edu" required aria-describedby="join-email-e" />
    <p class="cap-field-error" id="join-email-e" hidden></p>
  </div>
  <fieldset class="cap-field" aria-describedby="join-start-h">
    <legend class="cap-field-label">Start date <span class="cap-field-required" aria-hidden="true">Required</span></legend>
    <p class="cap-field-help" id="join-start-h">For example, 14 11 2026.</p>
    <div class="cap-date-input" data-error-date="Start date must be a real date.">
      <div class="cap-date-input-part"><label for="join-day">Day</label><input class="cap-input" id="join-day" name="start-day" data-cap-part="day" inputmode="numeric" pattern="[0-9]{1,2}" required autocomplete="off" data-error-value-missing="Start date must include a day." data-error-pattern-mismatch="Day must be a number." /></div>
      <div class="cap-date-input-part"><label for="join-month">Month</label><input class="cap-input" id="join-month" name="start-month" data-cap-part="month" inputmode="numeric" pattern="[0-9]{1,2}" required autocomplete="off" data-error-value-missing="Start date must include a month." data-error-pattern-mismatch="Month must be a number." /></div>
      <div class="cap-date-input-part"><label for="join-year">Year</label><input class="cap-input" id="join-year" name="start-year" data-cap-part="year" inputmode="numeric" pattern="[0-9]{4}" required autocomplete="off" data-error-value-missing="Start date must include a year." data-error-pattern-mismatch="Year must be four digits, such as 2026." /></div>
    </div>
    <p class="cap-field-error" hidden></p>
  </fieldset>
  <div><button type="submit" class="cap-btn" data-variant="primary">Join the team</button></div>
  <p class="cap-muted" id="join-result"></p>
</form>

The page's status region

<p class="cap-muted">Show and Hide, and a character count once typing stops, are said here.</p>
<div class="cap-message" data-cap="message" role="status" aria-label="Results and failures" aria-atomic="false"></div>

API reference

Field

PropTypeRequiredDoes
labelReactNodeYes
idstringThe control's id, for a control drawn by a function (an element child keeps its own).
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
requiredbooleanMarks the field required, on the label and on the control.
orientation"vertical" | "horizontal" | "responsive"vertical (default), horizontal (a checkbox beside its words), or responsive.
children| ReactElement<FieldControlProps> | ((props: FieldControlProps & { id: string }) => ReactNode)YesOne control: <input className="cap-input" />, a textarea or a select; or a function that is given the control's props and returns it inside its group (a password, a search).
afterReactNodeShown after the control, before the error: a character count.
actionReactNodeA button in the control's row, after it (Add, Check, Apply): one action on this field only.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
size"short""short": a field that needs only its control's room (a kind, a color) beside a long one, as data-size="short", which a layout reads (inline-add-form.css).

Check

PropTypeRequiredDoes
type"checkbox" | "radio"
labelReactNodeYes
variant"card"
indeterminateboolean

And every attribute of <input>.

Range

PropTypeRequiredDoes
valuenumberYes
minnumber
maxnumber

And every attribute of <input>.

InputGroup

PropTypeRequiredDoes
labelstring
childrenReactNode

InputGroupAddon

PropTypeRequiredDoes
align"inline-start" | "inline-end" | "block-start" | "block-end"
childrenReactNode

PasswordInput

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
autoComplete"current-password" | "new-password"

And every attribute of <input>.

CharacterCount

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
valuestringYes
limitnumberYes
wordsboolean

And every attribute of <textarea>.

NumberField

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
valuenumber | nullYes
onChange(value: number | null) => voidYes
minnumber
maxnumber
stepnumber | "any""any" takes any value (1.5 servings passes the browser's step check); the steppers and Page Up and Page Down then step by 1.
decreasestringThe steppers' names. Default: "Decrease" and "Increase" with the label, when it is text.
increasestring

And every attribute of <input>.

SearchField

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
valuestringYes
onChange(value: string) => voidYes
actionstring
landmarkstring

And every attribute of <input>.

DateInput

PropTypeRequiredDoes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
legendReactNodeYes
namestringYes
valueRecord<DatePart, string>Yes
onChange(value: Record<DatePart, string>) => voidYes
invalidDatePart[]
autoComplete"bday"
orderDatePart[]

FieldSet

PropTypeRequiredDoes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
legendReactNodeYes
idstring
childrenReactNodeYes

TextField

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
actionReactNodeA button in the input's row (Field's action).

And every attribute of <input>.

RangeField

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
valuenumberYes
onChange(value: number) => voidYes
minnumber
maxnumber
stepnumber
format(value: number) => string
minLabelReactNodeThe words under each end of the track; default the formatted min and max.
maxLabelReactNode

And every attribute of <input>.

SpanField

PropTypeRequiredDoes
labelReactNodeYes
names{ from: string; to: string }YesThe two ends' parameter names.
optionsreadonly { value: string; label: ReactNode }[]YesEvery value either end can take, in order, the same list for both.
fromstring | number | nullThe chosen ends; null or "" for an open end.
tostring | number | null

And every attribute of <fieldset>.

SlugField

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
maxnumberThe longest slug, cut back to a whole word (slugify's max).
valuestringYes
onChange(value: string) => voidYes
fromstring

And every attribute of <input>.

MoneyField

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
defaultCentsnumber | null
symbolstringThe sign inside the edge. Default "quot;.

And every attribute of <input>.

DateTimeField

PropTypeRequiredDoes
labelReactNodeYes
helpReactNodeHelp, shown between the label and the control and read as its description.
errorReactNodeThe message for a wrong value: what is wrong and what to do. Shown beside the control.
requiredbooleanMarks the field required, on the label and on the control.
announcebooleanAnnounce the error as it appears (role="alert"). Set it for errors found on submit; leave it off for errors found when a field is left.
labelHiddenbooleanThe label is read but not shown, for a field whose purpose the page already makes plain (a site's search box with its icon). Every other field shows its label.
helpPlacement"before" | "after"Help between the label and the control (default), or under the control.
showRequiredbooleanfalse keeps the control required but leaves the word "Required" off the label, for a form whose every field is required and says so once at the top.
defaultDateDate | null
timeZonestring

And every attribute of <input>.

Functions

FunctionSignatureDoes
isControl(el: unknown): el is Control
messageFor(control: Control): stringWhat to say about a control, or "" when it is valid. The control's own words first, then the browser's.
groupOf(control: Control): Control[]The controls that share one message: a radio group, or the control alone.
errorFor(control: Control): HTMLElement | null
showError(control: Control, text: string, announce?: boolean): voidShows a message beside a control. announce gives it role="alert": only for an error that appears after a submit; one found on leaving a field is read through aria-describedby when the field is next focused.
clearError(control: Control): void
validate(control: Control, announce?: boolean): booleanChecks one control and shows or clears its message. True when it is valid.
validateForm(form: HTMLFormElement): booleanChecks every field of a form. One field in error takes focus and its message is announced; two or more are listed in the error summary, which takes focus instead. The page title starts "Error: " until the form is valid. True when the form is valid.
dateFrom(year: number, month: number, day: number): Date | nullThe date a year, month and day make, or null when they make none (31 February).
checkDate(group: HTMLElement): voidA date input whose three parts are each well formed but make no real date is wrong on its day, in the group's data-error-date words. The parts are found by data-cap-part, so their order can follow the site's language (month first in American English).
setRevealed(input: HTMLInputElement, button: HTMLElement, shown: boolean): voidShow and Hide on a password (GOV.UK Password input): the type, the words and the name change together, and the change is said in the status region.
countText(value: string, limit: number, words?: boolean): { text: string; over: boolean; }What a character count says: how many are left, or how many too many (GOV.UK's words).
limitOf(control: HTMLElement): { limit: number; words: boolean; } | nullThe limit a control counts against: data-maxlength (characters) or data-maxwords.
stepValue(value: number, step: number, by: number, min?: number | undefined, max?: number | undefined): numberThe value a stepper or a key gives: by steps from the value, kept within min and max, to the step's own decimals so 0.1 + 0.2 is 0.3, or the value's where it has more (a field with step="any" steps 1.5 by 1 to 2.5).
keyValue(key: string, value: number, step: number, min?: number | undefined, max?: number | undefined): number | nullThe value Page Up, Page Down (ten steps), Home (min) or End (max) gives, as the APG spinbutton has them; null for another key, or a bound that is not set.
toDateTimeLocal(date: Date | null | undefined, timeZone?: string): stringA moment as the value a datetime-local input takes ("2026-11-11T08:30"), on the wall clock of timeZone (default UTC, the Worker's own zone). The empty string for no date or a bad one.
fromDateTimeLocal(value: FormDataEntryValue | null | undefined, timeZone?: string): Date | nullA datetime-local value back to the moment it names on the wall clock of timeZone; null when it does not parse. A wall time a clock change skips is read on the offset from before it.
keepFocus({ key, skip, }?: { key?: string | undefined; skip?: (() => boolean) | undefined; }): () => voidA plain GET search form (data-keep-focus) on a page with no client router loads its results afresh, and focus would go to the top. This puts it back on the control the person sent the form from (the field, caret at the end, or the button). Storage is read in try/catch: blocked, the page simply loads without it. skip returns true when the router submits in place (a hydrated app), where focus stays without help. Call once per page; returns the detach.
setValue(input: HTMLInputElement, value: string): voidSets a control's value as typing would, so the field's checks and a React onChange see it.
enhance(root?: Element | Document | DocumentFragment): () => voidAttaches to every form[data-cap="field"] under root that is not attached yet, and to every input group, password, character count and search field. The form gets novalidate, so the browser's own bubbles give way to the messages beside the fields. Returns a function that detaches them all. The root is Element | Document | DocumentFragment, not ParentNode: under @cloudflare/workers-types an HTMLFormElement does not type as a ParentNode, so a site could not pass its form.
revealedText(shown: boolean): string

CSS variables

VariableDefault
--cap-check-edgevar(--line-strong)
--cap-input-edgevar(--line-strong)
--cap-range-fill0%
--cap-range-tracklinear-gradient(to right, var(--primary) var(--cap-range-fill, 0%), var(--line-strong) 0)
--fields-gapvar(--space-5)
--fields-min16rem

Parts and data attributes

ClassIs
.cap-date-inputits own class
.cap-date-input-partits own class
.cap-fieldthe root
.cap-field-contenta part
.cap-field-counta part
.cap-field-descriptiona part
.cap-field-errora part
.cap-field-groupa part
.cap-field-helpa part
.cap-field-labela part
.cap-field-optionsa part
.cap-field-requireda part
.cap-field-rowa part
.cap-field-separatora part
.cap-field-titlea part
.cap-field-widea part
.cap-fieldsits own class
.cap-input-group-textits own class
.cap-range-field-endsits own class
.cap-range-field-headits own class
.cap-range-field-valueits own class
.cap-span-field-endits own class
.cap-span-field-endsits own class
AttributeValues
data-alignblock-end block-start inline-end inline-start
data-cap-partreveal step-up year
data-cap-readypresent or absent
data-invalidtrue
data-orientationhorizontal responsive
data-overtrue
data-variantcard code legend
StateRead from
:activethe platform
:checkedthe platform
:disabledthe platform
:emptythe platform
:focus-visiblethe platform
:hoverthe platform
:indeterminatethe platform
[aria-invalid="true"]an attribute
[hidden]an attribute

Accessibility

KeyDoes
TabMoves to the next field; leaving a field you changed checks it
SpaceChecks or unchecks a checkbox; selects a radio
Arrow keysMove between the radios of a group, selecting as they go
Enter in a one-line fieldSubmits the form. One field wrong: focus moves to it and its message is announced. Two or more: focus moves to the error summary
Enter or Space on ShowShows the password as text (the button becomes Hide); again hides it
Up and Down arrows in a numberStep the value by one step (the browser's own)
Page Up, Page Down in a numberStep it by ten steps, within min and max
Home, End in a numberGo to min and to max, when they are set
Esc in a search with textClears it; focus stays in the field
Enter or Space on ClearClears the search and puts focus back in the field
  • Every control has a visible label; a radio group is a fieldset.cap-field with a legend.cap-field-label.
  • The error has an icon as well as its color and a thicker edge, so it is not color alone.
  • Inputs are 16 px on a touch screen so iOS does not zoom (base.css).
  • The checkbox and radio are real <input>s, drawn by CSS (appearance: none): the edge is --line-strong (3:1), the checked fill --on (the primary fill unless the site sets its own on color), the tick --primary-fg. A mixed checkbox (input.indeterminate = true; there is no attribute) shows a bar and is announced as mixed.
  • The ring is an opaque 3 px in the accent on every field, checkbox and radio; the group draws it round the whole edge.
  • Clicking an input group's text or icon puts the cursor in its field (enhance(), or the React InputGroupAddon); a button inside keeps its own click.
  • Forced colors: the error icon is drawn in CanvasText and an invalid edge doubles.
  • Every part's button is at least --target (44 px on a touch screen); the steppers and Clear are icon buttons with a name.
  • Show and Hide, and the character count, are said through the page's one status region (Message) without moving focus, when the page has one; without one, the count is still read as the field's description when it is focused.