CynosureComponents / Controls
DateField
A date in a form: typed, stepped with the arrows, or picked from a calendar.
When to useLink to "When to use"
- A date in a form or a filter, where people may know the date (and type it) or want to see the month (and pick it).
Use something else when:
- the whole month should be on screen (a planner, a booking page): Calendar
- it is a time of day: TimeField
UsageLink to "Usage"
tsx
import { DateField } from "@arshad-shah/cynosure";
<DateField label="Due date" name="due" value={due} onChange={setDue} min="2026-01-01" />The value is a YYYY-MM-DD string or null. onChange reports only real, available dates: when typing is finished (blur or Enter), when the arrows step it, or when a day is picked.
Typing and mistakesLink to "Typing and mistakes"
Loose separators and single digits are tidied (2026/1/5 becomes 2026-01-05). Text that is not a date is kept for correcting and explained as the field's error; so is a date outside min and max or one isDateDisabled refuses.
PropsLink to "Props"
| Prop | What it does | Type | Default |
|---|---|---|---|
labelRequired | Visible label; it names the field. | ReactNode | |
labelHidden | Visually hide the label (it still names the field). Prefer visible labels. | boolean | |
description | Help text shown below the field. | ReactNode | |
error | Your own error; it replaces the field's own messages. | ReactNode | |
value | YYYY-MM-DD, or null when empty. | string | null | |
defaultValue | Starting date when uncontrolled, as YYYY-MM-DD. | string | null | |
onChange | A valid, available date (or null when cleared), when typing is finished or a day is picked. | ((date: string | null) => void) | |
min | Earliest date that can be typed or picked, as YYYY-MM-DD. | string | |
max | Latest date that can be typed or picked, as YYYY-MM-DD. | string | |
isDateDisabled | Return true for dates that cannot be chosen (fully booked, weekends). | ((date: string) => boolean) | |
locale | The calendar's locale and first day of the week. | string | |
weekStartsOn | 0 Sunday to 6 Saturday. Default: the locale's first day, else Monday. | number | the locale's first day |
today | What the calendar counts as today, as YYYY-MM-DD. Default: the device's date. | string | the device's date |
name | Name the date (YYYY-MM-DD, or empty) is submitted under in a form; text being typed is never submitted. | string | |
form | Id of the form it belongs to, when it is not inside that form. | string | |
required | Marks the field as required for form validation. | boolean | |
disabled | Turns off the field and the calendar button. | boolean | |
readOnly | The date can be read but not changed; the calendar button is hidden. | boolean | |
size | Size of the field. Default "md". | Size | "md" |
labels | Replace the built-in English text: the calendar button, the two error messages and the month buttons. | Partial<DateFieldLabels> | |
className | Added to the root element, for layout. | string | |
style | Layout only. | CSSProperties | |
layout | stack puts the label above the control and the description and error below it. split puts the label and description at the start and the control at the end of one row (a settings row); when the field is too narrow for both, the control moves under the text. Default "stack". | "stack" | "split" | "stack" |
width | Width of the control, so the controls of a column of fields line up: "sm", "md" and "lg" are the --cy-field-control-width-* tokens (never wider than the field), "full" is the whole field. Default: the control's own width (the whole field in the stacked layout for TextField and the other fields). | FieldWidth |
Generated from the type definitions in @arshad-shah/cynosure 0.5.0.
Behaviour and accessibilityLink to "Behaviour and accessibility"
| Key | Does |
|---|---|
| Enter | Finish typing |
| Up / Down | Next / previous day (Shift: month), within the limits |
| In the calendar | Arrows, Home, End, Page Up and Down move; Enter or Space chooses; Escape closes |
- Picker: a non-modal dialog named "Choose a date" that opens on the chosen day, as in the WAI-ARIA APG date picker. Choosing returns focus to the field.
- Errors are the field's description and set
aria-invalid.
TouchLink to "Touch"
The calendar button and every day have 44px hit areas on touch screens. The field asks for the numeric keyboard.
ThemingLink to "Theming"
No tokens of its own; it follows TextField, Popover and Calendar.
RelatedLink to "Related"
These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.