DatePicker
BasicInputs
<co-date-picker>DatePicker takes a date as MM/DD/YYYY by typing or from a month grid.
import { DatePicker } from 'health-components';
Examples
Showcase
Calendar Open
Invalid Date
Read Only
Usage
<DatePicker label="Date of Birth" required disableFuture defaultValue="03/14/1988" onChange={setDob} />
When to use
- Date of birth, date of service, coverage start and end, follow-up date.
When not to use
- Picking an appointment time: TimeSlotPicker.
Variants and states
| Variant | What it is |
|---|---|
| closed | Typed entry with mask. |
| open | Month grid, today ringed, selected filled. |
| limits | disablePast, disableFuture (DOB), disableWeekends (scheduling). |
| error | Bad or impossible date: "Enter a real date as MM/DD/YYYY." |
| readOnly | Lock state. |
Accessibility
- Typing always works; the grid is optional.
- Grid days are buttons with aria-selected and aria-current="date" for today; month changes are announced.
- The check on typed dates proves the date exists on the calendar. It does not prove it is plausible (a DOB of today): add that rule where it matters.
Do and don't
- Do: DOB with disableFuture.
- Don't: A three-dropdown date (month, day, year).
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label * | string | — | Visible label; required |
value | string | undefined (uncontrolled) | Controlled value, MM/DD/YYYY |
defaultValue | string | "" | Initial value (uncontrolled), MM/DD/YYYY |
onChange | (value: string) => void | none | Called with the MM/DD/YYYY text on typing and on picking a day |
today | string | the current date | Today's date, MM/DD/YYYY (marks the grid, limits past/future) |
open | boolean | undefined (uncontrolled) | Controlled open state of the calendar |
defaultOpen | boolean | false | Calendar open on first render (uncontrolled) |
onOpenChange | (open: boolean) => void | — | Called when the calendar opens or closes |
disablePast | boolean | false | Days before today cannot be picked |
disableFuture | boolean | false | Days after today cannot be picked (date of birth) |
disableWeekends | boolean | false | Saturdays and Sundays cannot be picked |
error | string | none | Error message (as TextField); an impossible typed date shows "Enter a real date as MM/DD/YYYY." |
helper | string | 'MM/DD/YYYY' | Muted hint under the field |
required | boolean | false | Red asterisk plus aria-required |
readOnly | boolean | false | Read-only lock state; the calendar button is disabled |
lockMessage | string | 'Your role can view but not edit' | Lock line text when readOnly |
style | CSSProperties | — | Inline style of the root |
Also accepts native attributes, including defaultChecked, autoFocus, onInput, type, disabled, name, max, step, placeholder, accept, autoComplete, checked, maxLength, min, multiple, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-date-picker>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
Angular template
<co-date-picker label="…" value="…" [style]="style" (co-change)="onChange($event.detail)"></co-date-picker>
| Kind | Name | Description |
|---|---|---|
| attribute | label | Visible label; required |
| attribute | value | Controlled value, MM/DD/YYYY; default undefined (uncontrolled) |
| attribute | default-value / defaultValue | Initial value (uncontrolled), MM/DD/YYYY; default "" |
| attribute | today | Today's date, MM/DD/YYYY (marks the grid, limits past/future); default the current date |
| attribute | open | Controlled open state of the calendar; default undefined (uncontrolled) |
| attribute | default-open / defaultOpen | Calendar open on first render (uncontrolled); default false |
| attribute | disable-past / disablePast | Days before today cannot be picked; default false |
| attribute | disable-future / disableFuture | Days after today cannot be picked (date of birth); default false |
| attribute | disable-weekends / disableWeekends | Saturdays and Sundays cannot be picked; default false |
| attribute | error | Error message (as TextField); an impossible typed date shows "Enter a real date as MM/DD/YYYY."; default none |
| attribute | helper | Muted hint under the field; default 'MM/DD/YYYY' |
| attribute | required | Red asterisk plus aria-required; default false |
| attribute | read-only / readOnly | Read-only lock state; the calendar button is disabled; default false |
| attribute | lock-message / lockMessage | Lock line text when readOnly; default 'Your role can view but not edit' |
| property / JSON attribute | style | Inline style of the root |
| attribute | default-checked / defaultChecked | |
| attribute | auto-focus / autoFocus | |
| property / JSON attribute | type | |
| attribute | disabled | |
| attribute | name | |
| property / JSON attribute | max | |
| property / JSON attribute | step | |
| attribute | placeholder | |
| attribute | accept | |
| property / JSON attribute | auto-complete / autoComplete | |
| attribute | checked | |
| attribute | max-length / maxLength | |
| property / JSON attribute | min | |
| attribute | multiple | |
| event | co-change | Called with the MM/DD/YYYY text on typing and on picking a day; default none (React: onChange) |
| event | co-open-change | Called when the calendar opens or closes (React: onOpenChange) |
| event | co-input | (React: onInput) |