J3W1 / DESIGN SYSTEM

Date picker

A themed date editor and calendar, alone or as a from/to pair, backed by native form values and constraints.

stable · LIGHT DOM · 1.1.0

Theme-owned date/time editor and controls backed by the original native input for form values and constraints. Native input is the no-JavaScript fallback.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

Release date

Within 2026.

✕ Choose a date in 2026.

<j3w1-date-picker id="example-date-picker-default"><div class="date-picker">
  <label class="date-picker-label" for="example-date-picker-default-dp-release">Release date</label>
  <div class="date-picker-root">
    <input class="date-picker-input" id="example-date-picker-default-dp-release" type="date" value="2026-09-06" min="2026-01-01" max="2026-12-31" aria-describedby="example-date-picker-default-dp-release-help example-date-picker-default-dp-release-message" name="example-date-picker-default-dp-release">
  </div>
  <p class="date-picker-help" id="example-date-picker-default-dp-release-help">Within 2026.</p>
  <p class="date-picker-message" id="example-date-picker-default-dp-release-message">✕ Choose a date in 2026.</p>
</div></j3w1-date-picker>

range

Report period

From

Inclusive; at most 92 days.

✕ The end date is before the start date.

<j3w1-date-picker id="example-date-picker-range"><fieldset class="date-picker date-picker-range">
  <legend class="date-picker-legend">Report period</legend>
  <div class="date-picker-pair">
    <div class="date-picker-half">
      <label class="date-picker-label" for="example-date-picker-range-dp-from">From</label>
      <div class="date-picker-root">
        <input class="date-picker-input" id="example-date-picker-range-dp-from" type="date" value="2026-09-01" aria-describedby="example-date-picker-range-dp-range-help example-date-picker-range-dp-range-message" name="example-date-picker-range-dp-from">
      </div>
    </div>
    <span class="date-picker-separator" aria-hidden="true">–</span>
    <div class="date-picker-half">
      <label class="date-picker-label" for="example-date-picker-range-dp-to">To</label>
      <div class="date-picker-root">
        <input class="date-picker-input" id="example-date-picker-range-dp-to" type="date" value="2026-09-30" aria-describedby="example-date-picker-range-dp-range-help example-date-picker-range-dp-range-message" name="example-date-picker-range-dp-to">
      </div>
    </div>
  </div>
  <p class="date-picker-help" id="example-date-picker-range-dp-range-help">Inclusive; at most 92 days.</p>
  <p class="date-picker-message" id="example-date-picker-range-dp-range-message">✕ The end date is before the start date.</p>
</fieldset></j3w1-date-picker>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@1.1.0

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/date-picker.css';
import '@j3w1/ui/register/date-picker';

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy date-picker --out ./vendor/j3w1/date-picker

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.
`value`	`CustomEvent`	Forwards value to the primary native control.
`required`	`CustomEvent`	Forwards required to the primary native control.
`readonly`	`CustomEvent`	Forwards readonly to the primary native control.
`checked`	`CustomEvent`	Forwards checked to the primary native control.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.
`value`	`string`	Primary native value; assignment does not fabricate user events.
`checked`	`boolean`	Native checkbox state.
`required`	`boolean`	Native required constraint.
`readOnly`	`boolean`	Native readonly property.
`form`	`HTMLFormElement \| null`	Owning native form. Read only.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.
`checkValidity`	`(): boolean`	Check owned native constraints.
`reportValidity`	`(): boolean`	Report the first invalid owned control.
`clear`	`(): void`	Clear an editable primary input and emit native input/change.

events

Name	Type / signature	Meaning
`j3w1-change`	`CustomEvent`	Native change from an owned control, alongside the original native event.

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Purpose

Choose a date by explicit text entry or a themed calendar. A range is two separately labeled date controls. D-025 requires theme-owned web controls rather than browser popup styling.

Anatomy

A label, editor, calendar trigger, format hint and validation message. The native date input remains the successful form control and owns its value, defaults and constraints. It is hidden only after enhancement.

States

State	Treatment
default	Input surface, default text and control border.
hover	The declared hover fill.
focus-visible	Active border and the canonical focus ring.
invalid	Danger border and a linked message.
invalid+focus-visible	Danger border plus the container focus ring.
disabled	Disabled colors; editor and calendar actions unavailable.
read-only	Readable canvas text and bottom edge; calendar action unavailable.

Use the declared state tokens: default input surface and control border; hover fill; the canonical focus ring; danger border and message for invalid input; disabled colors and unavailable actions. Read-only values remain readable and cannot open a picker or change through step buttons. The date read-only treatment retains the canvas surface and unobtrusive bottom edge.

Keyboard

Alt+Down opens the calendar. Arrows move by a day or week, Home/End reach week boundaries, and PageUp/PageDown change months. Enter/Space chooses a focused date. Escape closes and restores editor focus. Tab leaves normally; the calendar is a nonmodal popup.

Accessibility

The visible editor receives the original label, descriptions, required state and error state. Format hints are always available. Native min, max, step and required constraints remain authoritative. Invalid entry focuses the visible editor and exposes a theme-owned message. Calendar selection is a fill; keyboard focus is a separate ring. Disabled dates cannot be selected. The range validates that its end is not before its start. Form reset restores the native defaults.

Automated evidence records its actual browser, states and limitations; it is not a manual screen-reader acceptance.

Portability

The package and complete copy distribution include the renderer. The public control enhancement applies the same behavior to existing native markup. The no-JavaScript fallback and non-web platform mappings remain native.

Non-examples

An unthemed host popup presented as fully themed. A second named input that duplicates form values. Discarding native constraints, labels or reset behavior. Literal colors, rounded corners, or a selected fill with no distinguishable focus boundary.