Date Textbox

Installation

npm install @nib-group/mesh-date-textbox

Companion dependencies

This component uses date objects from Adobe's @internationalized/date package instead of native JavaScript Date objects. Types like CalendarDate represent a calendar date without time or timezone, making them ideal for date-only inputs. Install this package to create or manipulate date values for props like value, defaultValue, minValue, and maxValue:

npm install @internationalized/date

Usage

import DateTextbox from '@nib-group/mesh-date-textbox';

Interactive demo

() => {
  return <DateTextbox label="Date of birth" valid={false} validated={false} error="Please enter a date." />;
};

With min/max constraints

Use minValue and maxValue to restrict the allowed date range. The component will automatically show validation error styling when the entered date falls outside the specified range.

<DateTextbox label="Appointment date" minValue={parseDate('2025-01-01')} maxValue={parseDate('2025-12-31')} error="Date must be between 1 Jan 2025 and 31 Dec 2025" />

With controlled value

Use value and onChange to control the date value programmatically.

() => {
  const [date, setDate] = React.useState(parseDate('2020-02-03'));

  return (
    <>
      <DateTextbox label="Event date" value={date} onChange={setDate} />
      <Copy>Selected date: {date ? date.toString() : '--'}</Copy>
    </>
  );
};

Props

This component should not be wrapped in a FormControl. It supports many of the same props directly.

The <DateTextbox/> extends React Aria's DateFieldProps and supports all its props.

When to use Date Textbox vs Date Picker

Use Date Textbox when the user already knows the date and can type it directly. Use Date Picker when a calendar popup helps the user browse and select a date.

Considerations

Labels

Label your date textbox clearly to indicate the expected date. Use natural language such as "Date of birth" or "Policy start date" rather than generic labels like "Date".

Help text

Use the help prop to guide the user on the expected format or provide context, for example: "DD/MM/YYYY", "As shown on your passport" or "Must be within the last 12 months".

Validation and errors

Validation should happen in real-time so the user can fix errors as they occur. When the user enters an invalid date, provide an informative error message that helps them correct the input.

• Good: "Please enter a date between 1 Jan 2025 and 31 Dec 2025"
• Good: "Date of birth must be in the past"
• Avoid: "Invalid date"

Use minValue and maxValue to automatically validate against date boundaries. The component will show the error message when the entered date falls outside the allowed range.

Autocomplete

Use the autoComplete attribute to help users fill in known dates faster. For example, use autoComplete="bday" for date of birth fields.

<DateTextbox label="Date of birth" autoComplete="bday" />

For a list of valid autocomplete values, refer to this HTML autocomplete attribute resource.

Accessibility

• The component uses segmented fields (DD/MM/YYYY) which are individually navigable via keyboard arrow keys and Tab.
• Each segment is announced to screen readers with its label (e.g. "day", "month", "year").
• Error messages are linked to the input via aria-describedby, so screen readers announce them automatically.
• Do not rely on colour alone to communicate validation state — the component uses both colour and icons.

Internationalisation

The date textbox can be configured to support internationalisation by wrapping it in React Aria's I18nProvider. This changes the segment order and labels to match the specified locale (e.g. MM/DD/YYYY for US English). See the React Aria DateField internationalisation documentation for more info.

import {I18nProvider} from 'react-aria';

function InternationalDateTextbox() {
  return (
    <I18nProvider locale="en-US">
      <DateTextbox label="Date of birth" />
    </I18nProvider>
  );
}

Related components

• Date Picker
• Form Control