Skip to content

Date picker

A text input that takes a date, with a button that opens a calendar and works without script.

<form class="cap-field-options" id="dp-form" data-cap="field" action="#saved" aria-labelledby="s-default">
  <div class="cap-field">
    <label class="cap-field-label" for="dp-due">Publish on</label>
    <p class="cap-field-help" id="dp-due-h">Year, month and day, for example 2026-11-14.</p>
    <div class="cap-date-picker" data-cap="date-picker">
      <div class="cap-input-group">
        <input class="cap-input" id="dp-due" name="publish" pattern="\d{4}-\d{1,2}-\d{1,2}" autocomplete="off" aria-describedby="dp-due-e dp-due-h" value="2026-11-14" data-min="2026-10-01" data-max="2027-12-31" data-error-pattern-mismatch="Enter the date as year, month and day, such as 2026-11-14." />
        <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="open" aria-label="Choose date" hidden>
            <svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><rect x="2.5" y="3.5" width="11" height="10" rx="1.5" fill="none" stroke="currentColor" stroke-width="1.5" /><path d="M2.5 6.5h11M5.5 2v3M10.5 2v3" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg>
          </button>
        </div>
      </div>
    </div>
    <p class="cap-field-error" id="dp-due-e" hidden></p>
  </div>
  <div><button type="submit" class="cap-btn" data-variant="primary">Schedule the post</button></div>
</form>

Installation

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

enhance();

Usage

<div class="cap-field">
  <label class="cap-field-label" for="due">Publish on</label>
  <p class="cap-field-help" id="due-h">Year, month and day, for example 2026-11-14.</p>
  <div class="cap-date-picker" data-cap="date-picker">
    <div class="cap-input-group">
      <input class="cap-input" id="due" name="publish" pattern="\d{4}-\d{1,2}-\d{1,2}" autocomplete="off" aria-describedby="due-h"
        data-min="2026-10-01" data-max="2027-12-31" data-error-date="Enter a date that exists." />
      <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="open" aria-label="Choose date" hidden>[calendar icon]</button>
      </div>
    </div>
  </div>
  <p class="cap-field-error" hidden></p>
</div>
import { DatePicker } from "capsomer/react/date-picker";
<DatePicker label="Publish on" help="Year, month and day, for example 2026-11-14." name="publish" min="2026-10-01" value={date} onChange={(e) => setDate(e.target.value)} />

Examples

The calendar open

<main class="specimen-page" id="main" tabindex="-1">
  <h1>Schedule a post</h1>
  <div class="cap-field">
    <label class="cap-field-label" for="dp-open">Publish on</label>
    <div class="cap-date-picker" data-cap="date-picker">
      <div class="cap-input-group">
        <input class="cap-input" id="dp-open" name="publish" pattern="\d{4}-\d{1,2}-\d{1,2}" autocomplete="off" value="2026-11-14" data-min="2026-11-03" />
        <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="open" aria-label="Choose date" hidden data-specimen-open>
            <svg viewBox="0 0 16 16" aria-hidden="true" focusable="false"><rect x="2.5" y="3.5" width="11" height="10" rx="1.5" fill="none" stroke="currentColor" stroke-width="1.5" /><path d="M2.5 6.5h11M5.5 2v3M10.5 2v3" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg>
          </button>
        </div>
      </div>
    </div>
  </div>
</main>

API reference

DatePicker

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.
minstring
maxstring

And every attribute of <input>.

Functions

FunctionSignatureDoes
parseDate(text: string): Date | nullThe date in 2026-11-14 (a month or day may be one digit), or null when it is not a real one.
addMonths(d: Date, n: number): DateThe same day n months on, or the month's last day when it has fewer (31 January to 28 February).
moveDate(d: Date, key: string, shift?: boolean): Date | nullWhere a key in the grid moves the focused day (APG's table), or null for a key it ignores.
wirePicker(group: HTMLElement): () => voidWires one picker: group (.cap-date-picker) holds the input and the [data-cap-part="open"] button, in an input group; the dialog is added inside it. min and max (data-min, data-max on the input, as 2026-11-14) make the days outside them unchoosable.
enhance(root?: ParentNode): () => voidWires every [data-cap="date-picker"] under root not yet wired. Returns a function that detaches them all.
isoDate(d: Date): string

Parts and data attributes

ClassIs
.cap-date-pickerthe root
.cap-date-picker-grida part
.cap-date-picker-heada part
AttributeValues
data-datepresent or absent
StateRead from
:focus-visiblethe platform
:hoverthe platform
[aria-current="date"]an attribute
[aria-disabled="true"]an attribute
[aria-selected="true"]an attribute

Accessibility

KeyDoes
Enter or Space on the calendar buttonOpens the calendar, with focus on the input's date (or today)
EscCloses the calendar with nothing changed; focus goes back to the button
Tab, Shift TabMove between the month and year buttons, the grid, Cancel and Choose; focus stays in the calendar
Enter or Space on Previous or Next month, Previous or Next yearShows that month; the focused day moves with it
Right arrow, Left arrowThe next day, the day before
Down arrow, Up arrowThe same day next week, last week
Home, EndThe first day of the week (Sunday), the last (Saturday)
Page Up, Page DownThe same day last month, next month (the last day of a shorter month)
Shift Page Up, Shift Page DownThe same day last year, next year
Enter or Space on a dayChooses it and closes the calendar; focus goes back to the button
Enter or Space on ChooseChooses the focused day and closes the calendar
Enter or Space on CancelCloses the calendar with nothing changed
  • The calendar is a dialog named "Choose a date", opened with showModal(); the grid is a table with role="grid", named by the month heading, with a column header (abbr the full day name) for each day of the week. One day is in the Tab order at a time (roving tabindex); the chosen day has aria-selected="true", a day that cannot be chosen aria-disabled="true".
  • The month and year buttons are icon buttons named "Previous year", "Previous month", "Next month", "Next year"; every day and button is at least --target.
  • The calendar button is an icon button named "Choose date", then "Change date, " and the date.
  • Forced colors: the chosen day is drawn in Highlight, a day that cannot be chosen in GrayText; today keeps its underline.
  • Right to left: the grid follows dir; the arrows keep APG's meaning (Right arrow is the next day).