react.form.date-field
A labelled date picker (<input type="date">) with min and max, checked by form.iso-date, its error shown accessibly.
React ^19 · TypeScript only A React component: use it from a TypeScript project with React installed. A client component ("use client").
1.0.0 · published 2026-10-10 by charlie · Anterra
Pinned by 14 tests, run in TypeScript.
What it does
The browser's own date picker, `<input type="date">`, labelled and described the GOV.UK way, with its value checked by `form.iso-date`.
"use client";
import { DateField } from "#fune/react.form.date-field@^1";
<DateField id="start" label="Start date" required
rules={{ today, timing: "future-or-today", notBefore: null, notAfter: "2027-12-31" }}
value={start} onChange={setStart} showError={submitted} />
For example
-
a plain date picker: type date, submitted under its id
<DateField id="start" label="Start date" />renders
<div class="fune-field"><label class="fune-label" for="start">Start date</label><input class="fune-input fune-date-field" id="start" type="date" name="start"/></div> -
required, with earliest and latest as the picker's min and max
<DateField id="start" label="Start date" required rules={{"today":null,"timing":null,"notBefore":"2026-01-01","notAfter":"2026-12-31"}} />renders
<div class="fune-field"><label class="fune-label" for="start">Start date</label><input class="fune-input fune-date-field" id="start" type="date" min="2026-01-01" max="2026-12-31" required="" name="start"/></div>
The function
Written for React ^19, in TypeScript only. A component: it takes its props and renders HTML, which the tests below pin exactly.
A React capability: React ^19 · TypeScript only. This capability has no Python implementation, so it is shown in TypeScript. A Python project cannot use it: fune build stops and names where it was required. Your choice of Python is kept for every other page.
export function DateField(props: DateFieldProps): JSX.Element
Its props, DateFieldProps. A ? marks one the caller may leave out.
| label | ReactNode | the question, such as "Start date" |
| id? | string | the input's id; React's useId() when left out |
| name? | string | what the date is submitted as; the id when left out |
| hint? | ReactNode | help under the label, such as "For example, 27 3 2026" |
| messageLabel? | string | the date's name in error messages; the label when it is text, else "Date" |
| required? | boolean | an empty date is an error |
| rules? | DateRules | form.date-parts' rules; notBefore and notAfter also become the picker's min and max |
| showError? | boolean | check the current value and show the message: after the field is touched or the form submitted |
| error? | ReactNode | an error to show instead, such as the server's answer; marks the input invalid |
| value? | string | the date, YYYY-MM-DD or "", for a controlled input (with onChange) |
| defaultValue? | string | the starting date, for an uncontrolled one |
| onChange? | (value: string) => void | called with the picker's value, YYYY-MM-DD or "" when cleared |
| onBlur? | () => void | called when the input loses focus, to mark the field touched |
| autoComplete? | string | bday for a date of birth |
| disabled? | boolean | shown but not editable, and not submitted |
| className? | string | added to the wrapper's classes |
| renders | JSX.Element |
The type it declares, generated into your project
/** One date chosen from the browser's date picker, as YYYY-MM-DD. */
export interface DateFieldProps {
/** the question, such as "Start date" */
readonly label: ReactNode;
/** the input's id; React's useId() when left out */
readonly id?: string;
/** what the date is submitted as; the id when left out */
readonly name?: string;
/** help under the label, such as "For example, 27 3 2026" */
readonly hint?: ReactNode;
/** the date's name in error messages; the label when it is text, else "Date" */
readonly messageLabel?: string;
/** an empty date is an error */
readonly required?: boolean;
/** form.date-parts' rules; notBefore and notAfter also become the picker's min and max */
readonly rules?: DateRules;
/** check the current value and show the message: after the field is touched or the form submitted */
readonly showError?: boolean;
/** an error to show instead, such as the server's answer; marks the input invalid */
readonly error?: ReactNode;
/** the date, YYYY-MM-DD or "", for a controlled input (with onChange) */
readonly value?: string;
/** the starting date, for an uncontrolled one */
readonly defaultValue?: string;
/** called with the picker's value, YYYY-MM-DD or "" when cleared */
readonly onChange?: (value: string) => void;
/** called when the input loses focus, to mark the field touched */
readonly onBlur?: () => void;
/** bday for a date of birth */
readonly autoComplete?: string;
/** shown but not editable, and not submitted */
readonly disabled?: boolean;
/** added to the wrapper's classes */
readonly className?: string;
}
Your code names it in one line, in the file that uses it
import { DateField } from "#fune/react.form.date-field@^1";
Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.
"use client";
import { useId, useState, type JSX, type ReactNode } from "react";
import type { DateRules } from "./form_date_parts.ts"; ← from form.date-parts ^1.0.0 · built alongside by fune
import { validateIsoDate } from "./form_iso_date.ts"; ← from form.iso-date ^1.0.0 · built alongside by fune
import { FormField, fieldIds } from "./react_form_form_field.ts"; ← from react.form.form-field ^1.0.0 · built alongside by fune
import type { DateFieldProps } from "./react_form_date_field_types.ts";
const NO_RULES: DateRules = { today: null, timing: null, notBefore: null, notAfter: null };
function present(node: ReactNode): boolean {
return node !== null && node !== undefined && node !== false && node !== "";
}
/**
* The browser's own date picker, labelled and described the GOV.UK way. Its
* value is always YYYY-MM-DD (or ""), whatever the person's locale shows, and
* validateIsoDate checks it as a calendar date: no Date object, no time zone,
* so 2026-03-29 is the same day in London, Sydney and on the server. The
* rules' earliest and latest dates become the picker's min and max, and
* "today" for a past or future rule is the caller's, worked out in the
* person's own time zone.
*
* GOV.UK asks for a date someone already knows (a date of birth) as three
* boxes (react.form.date-input); a picker suits a date being chosen, such as
* an appointment.
*/
export function DateField(props: DateFieldProps): JSX.Element {
const auto = useId();
const { label, hint, required, showError, error, value, defaultValue, onChange, onBlur, autoComplete, disabled, className } = props;
const id = props.id ?? auto;
const rules = props.rules ?? NO_RULES;
const [own, setOwn] = useState<string>(defaultValue ?? "");
const current = value ?? own;
const messageLabel = props.messageLabel ?? (typeof label === "string" ? label : "Date");
const check = validateIsoDate(current, messageLabel, required ?? false, rules);
const shown: ReactNode = present(error) ? error : showError && !check.valid ? check.message : null;
const ids = fieldIds(id, present(hint), present(shown));
return (
<FormField id={id} label={label} hint={hint} error={shown} className={className}>
<input
className={ids.error ? "fune-input fune-input--error fune-date-field" : "fune-input fune-date-field"}
id={ids.control}
name={props.name ?? id}
type="date"
min={rules.notBefore ?? undefined}
max={rules.notAfter ?? undefined}
value={value}
defaultValue={value === undefined ? defaultValue : undefined}
autoComplete={autoComplete}
required={required || undefined}
disabled={disabled}
aria-describedby={ids.describedBy ?? undefined}
aria-invalid={ids.error ? true : undefined}
onChange={(event) => {
setOwn(event.target.value);
onChange?.(event.target.value);
}}
onBlur={onBlur ? () => onBlur() : undefined}
/>
</FormField>
);
}Install
npm install react react-dom
fune build
With that line in your source, in a TypeScript project (language typescript in fune.project) with React ^19 installed (Functional Weave does not ship it, and fune build stops with the npm install line if it is missing), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:
fune add react.form.date-field
The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./react.form.date-field-1.0.0-typescript.fune, or fetch it from a terminal with fune pull react.form.date-field@1.0.0:typescript.
It is React ^19 · TypeScript only, so there is no package for Python or Rust. The full package is one file too: react.form.date-field-1.0.0.fune, 19,117 bytes, sha256 bfde1d2d881453012b7feef967d8170733b6456fed86d31f2356be3813e4c115.
Customise it in your app
The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.
before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.
// fune: before react.form.date-field
after — your function gets the result and the arguments, and returns the final result.
// fune: after react.form.date-field
replace — inside this capability’s code only, calls to a dependency go to your function, with the same signature. Other capabilities that use it are unaffected; write in * to replace it everywhere.
// fune: replace form.date-parts in react.form.date-field
// fune: replace form.iso-date in react.form.date-field
// fune: replace react.form.form-field in react.form.date-field
step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show react.form.date-field --steps.
// fune: step react.form.date-field after <n|label>
Tests
A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript alone, with the React in tooling/react, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json. A component’s tests are render tests: the props go in, and the HTML renderToStaticMarkup makes of them has to match exactly; a React warning during the render fails the test.
-
a plain date picker: type date, submitted under its id
<DateField id="start" label="Start date" />renders
<div class="fune-field"><label class="fune-label" for="start">Start date</label><input class="fune-input fune-date-field" id="start" type="date" name="start"/></div> -
required, with earliest and latest as the picker's min and max
<DateField id="start" label="Start date" required rules={{"today":null,"timing":null,"notBefore":"2026-01-01","notAfter":"2026-12-31"}} />renders
<div class="fune-field"><label class="fune-label" for="start">Start date</label><input class="fune-input fune-date-field" id="start" type="date" min="2026-01-01" max="2026-12-31" required="" name="start"/></div> -
a hint describes the input; a controlled value
<DateField id="appt" label="Appointment date" hint="For example, 27 3 2026" value="2026-03-27" />renders
<div class="fune-field"><label class="fune-label" for="appt">Appointment date</label><div class="fune-hint" id="appt-hint">For example, 27 3 2026</div><input class="fune-input fune-date-field" id="appt" type="date" aria-describedby="appt-hint" name="appt" value="2026-03-27"/></div> -
empty and required with showError: Enter the date
<DateField id="start" label="Start date" required showError value="" />renders
<div class="fune-field fune-field--error"><label class="fune-label" for="start">Start date</label><p class="fune-error-message" id="start-error"><span class="fune-visually-hidden">Error:</span> Enter start date</p><input class="fune-input fune-input--error fune-date-field" id="start" type="date" required="" aria-describedby="start-error" aria-invalid="true" name="start" value=""/></div> -
before the earliest date with showError: the date-parts message
<DateField id="start" label="Start date" showError rules={{"today":null,"timing":null,"notBefore":"2026-01-01","notAfter":null}} value="2025-12-31" />renders
<div class="fune-field fune-field--error"><label class="fune-label" for="start">Start date</label><p class="fune-error-message" id="start-error"><span class="fune-visually-hidden">Error:</span> Start date must be the same as or after 1 January 2026</p><input class="fune-input fune-input--error fune-date-field" id="start" type="date" min="2026-01-01" aria-describedby="start-error" aria-invalid="true" name="start" value="2025-12-31"/></div> -
in the past when it must be in the future, by the caller's today
<DateField id="appt" label="Appointment date" showError rules={{"today":"2026-10-10","timing":"future","notBefore":null,"notAfter":null}} value="2026-10-10" />renders
<div class="fune-field fune-field--error"><label class="fune-label" for="appt">Appointment date</label><p class="fune-error-message" id="appt-error"><span class="fune-visually-hidden">Error:</span> Appointment date must be in the future</p><input class="fune-input fune-input--error fune-date-field" id="appt" type="date" aria-describedby="appt-error" aria-invalid="true" name="appt" value="2026-10-10"/></div> -
a date that does not exist (typed where there is no picker)
<DateField id="start" label="Start date" showError value="2026-02-30" />renders
<div class="fune-field fune-field--error"><label class="fune-label" for="start">Start date</label><p class="fune-error-message" id="start-error"><span class="fune-visually-hidden">Error:</span> Start date must be a real date</p><input class="fune-input fune-input--error fune-date-field" id="start" type="date" aria-describedby="start-error" aria-invalid="true" name="start" value="2026-02-30"/></div> -
an error is checked only when showError is set
<DateField id="start" label="Start date" required value="" />renders
<div class="fune-field"><label class="fune-label" for="start">Start date</label><input class="fune-input fune-date-field" id="start" type="date" required="" name="start" value=""/></div> -
a valid date with showError shows no error
<DateField id="start" label="Start date" required showError defaultValue="2026-06-15" />renders
<div class="fune-field"><label class="fune-label" for="start">Start date</label><input class="fune-input fune-date-field" id="start" type="date" required="" name="start" value="2026-06-15"/></div> -
messageLabel names the date in messages instead of the label
<DateField id="dob" label="Date of birth" messageLabel="Your date of birth" required showError value="" autoComplete="bday" />renders
<div class="fune-field fune-field--error"><label class="fune-label" for="dob">Date of birth</label><p class="fune-error-message" id="dob-error"><span class="fune-visually-hidden">Error:</span> Enter your date of birth</p><input class="fune-input fune-input--error fune-date-field" id="dob" type="date" autoComplete="bday" required="" aria-describedby="dob-error" aria-invalid="true" name="dob" value=""/></div>
Show the other 4 tests
-
an error passed in wins, and is described after the hint
<DateField id="start" label="Start date" hint="The first day of the course" error="Courses cannot start on a bank holiday" value="2026-12-25" />renders
<div class="fune-field fune-field--error"><label class="fune-label" for="start">Start date</label><div class="fune-hint" id="start-hint">The first day of the course</div><p class="fune-error-message" id="start-error"><span class="fune-visually-hidden">Error:</span> Courses cannot start on a bank holiday</p><input class="fune-input fune-input--error fune-date-field" id="start" type="date" aria-describedby="start-hint start-error" aria-invalid="true" name="start" value="2026-12-25"/></div> -
name, disabled and a class of its own
<DateField id="start" name="startDate" label="Start date" disabled className="app-date" />renders
<div class="fune-field app-date"><label class="fune-label" for="start">Start date</label><input class="fune-input fune-date-field" id="start" type="date" disabled="" name="startDate"/></div> -
a malformed rule date throws even before the date is checked
<DateField id="start" label="Start date" rules={{"today":null,"timing":null,"notBefore":"2026-13-01","notAfter":null}} />error: 2026-13-01
-
a timing rule without today throws
<DateField id="start" label="Start date" rules={{"today":null,"timing":"past","notBefore":null,"notAfter":null}} />error: rules.today is needed
Verification
Verified by the operator, not the sandbox 14 test vectors declared; none run by the registry.
Verified locally by the registry's operator, not by the sandbox. This version was published with FUNE_VERIFY_MODE=inline-dev (the operator's import of the first-party registry, or a development server): the server validated the package - its manifest, signatures, imports, safety lint and test rules - but the registry did not run its test vectors in its sandbox. The operator runs them with `fune verify --all` before importing.
Signed by the registry with key fw-9dc887227da47575 (ed25519), over its integrity and this report's digest. The full report · JSON
More from the author
- **Timezone-safe.** The picker's value is always `YYYY-MM-DD` (or `""`), whatever the person's locale displays, and `validateIsoDate` compares it as a calendar date: no `Date` object, no UTC conversion, no off-by-one day for someone east or west of the server. `today`, for a past or future rule, is the caller's: work it out in the person's time zone (for example with `Intl.DateTimeFormat("en-CA", { timeZone })`), never from the server's clock. - **min and max.** `rules.notBefore` and `rules.notAfter` become the picker's `min` and `max`, so the calendar greys out the dates it would refuse, and the same rules give the message if one is typed anyway. - **Messages** are `form.date-parts`' wording ("Start date must be today or in the future", "Start date must be a real date"), named by `messageLabel`, or the label when it is plain text. - **When to use it.** GOV.UK recommends three boxes (`react.form.date-input`) for a date people already know, such as a date of birth, and a picker only for one being chosen, such as an appointment. - `showError` turns the check on (after touch or submit); `error` shows the server's message instead. `aria-describedby` names the hint then the error, and `aria-invalid="true"` is set only while an error shows.
It is a client component. Classes: those of `react.form.form-field`, plus `fune-input`, `fune-input--error` and `fune-date-field`.
Sources: GOV.UK Design System, "Dates" pattern https://design-system.service.gov.uk/patterns/dates/ ; HTML, the date state of the input element https://html.spec.whatwg.org/multipage/input.html#date-state-(type=date) .
## Notices
Portions derived from GOV.UK Frontend (https://github.com/alphagov/govuk-frontend), Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT License; the full notice is in NOTICE.
Files
| Path | Bytes |
|---|---|
| NOTICE | 1,219 |
| README.md | 2,297 |
| impl/typescript.tsx | 2,832 |
| vectors.json | 7,036 |