# Date input Lets users enter a memorable date, such as a date of birth. ## Preview ```html title="Date of birth"
Date of birth For example, 27 3 1990
``` ```tsx import { useState } from 'react'; import { DateInput, type DateInputValue } from '@govtech-bb/react'; const [dob, setDob] = useState({ day: '', month: '', year: '', }); ; ``` `value` and `onChange` drive the three fields as one `{ day, month, year }` object, and `name="dob"` names the fields `dob-day`, `dob-month`, `dob-year`. The HTML example above submits `dob[day]`, `dob[month]`, `dob[year]`. Read the matching field names on the server, or override the React input names through `dayProps`, `monthProps` and `yearProps` to match an existing server contract. `formatDateInput` and `parseDateInput` convert the value object to and from an ISO `YYYY-MM-DD` string when you need one, such as when submitting to an API. The Date Input component lets users enter a memorable date, such as a date of birth or a document's expiry date, using three short text fields for day, month, and year. A shared `
` and `` group the three fields under a single question. ## Usage

When to use

  • Use a date input for a date users already know or can look up without a calendar, such as a date of birth or passport expiry date.
  • Use separate day, month and year fields when the complete date is required.

When not to use

  • Do not use it when users need to browse available dates, such as booking an appointment; use a date picker.
  • Do not use dropdowns for the day or year because long option lists are difficult to scan.
## Best practices ### Make the expected format clear Label each field and give a Barbados-appropriate example such as “For example, 27 3 1990”. Keep the order day, month, year and do not move focus automatically between fields. ### Help browsers fill in known dates When asking for a date the user's browser may already know, set the matching `autocomplete` tokens — `bday-day`, `bday-month` and `bday-year` for a date of birth — so the fields can be filled automatically (WCAG 1.3.5). Skip it for dates the browser cannot know, such as a planned travel date. ### Validate the date as a whole Accept reasonable month formats, then check that the date exists and meets the service rules. Explain whether the day, month, year or complete date needs correction. ## Labels and hint text Give the fieldset a clear `` that states the question, such as "Date of birth", and label each field "Day", "Month", and "Year". Use hint text (`.govbb-hint`) below the legend to show an example format, such as "For example, 27 3 1990", and link it to the fieldset with `aria-describedby`. Set `inputmode="numeric"` on each field so mobile keyboards show digits, and do not require leading zeros: accept both "3" and "03". ## Errors Validate the whole date together on the server and report a single error message (`.govbb-error-message`) above the fields with `role="alert"`, rather than one error per field. Mark every field in the group with `aria-invalid="true"` so screen reader users understand the whole date is in question, not just one part of it. ```html title="Date of birth with error"
Date of birth For example, 27 3 1990 Date of birth must be a real date
``` ```tsx import { DateInput } from '@govtech-bb/react'; ; ``` With `name="dob"`, the default input IDs are `dob-day`, `dob-month` and `dob-year`. An error-summary link for the whole date should target `#dob-day`. Use `dayProps.id`, `monthProps.id` and `yearProps.id` for custom input IDs, and update the summary link to match. An `id` on `DateInput` identifies the fieldset; it does not rename its inputs. Give multiple date inputs unique names or IDs. The React `error` prop associates the error with the fieldset and marks all three inputs invalid. Preserve entered values when rendering the error, and move focus to the error summary after a failed submission as described on the [Error summary page](/components/error-summary/).