Skip to main content
On this page

Date Field

A three-part form field for entering a day, month, and year separately

Deprecated - dateField is deprecated. For most new work, use DatepickerField instead. DateField is documented here for teams maintaining existing code.

When to use​

  • When the user needs to enter a date they know by heart, such as their date of birth or passport expiry date
  • When the date is historical and calendar navigation would be impractical
  • When maintaining existing code that already uses DateField

When not to use​

  • For recent or upcoming dates - a calendar helps users pick dates they do not know precisely. Use DatepickerField instead.
  • For any new work - dateField is deprecated. Use DatepickerField instead.
  • To indicate that a field is unavailable - the disabled state is not supported. Use Summary List to show values that cannot be edited, or conditionally hide the field if it is not relevant in the current context.

Anatomy​

  1. Label (describes the date being collected, rendered as a fieldset legend)
  2. Required/Optional indicator
  3. Hint (shown below the label, above the inputs; always include the example format)
  4. Day input (numeric input labelled "Day")
  5. Month input (numeric input labelled "Month")
  6. Year input (numeric input labelled "Year")
  7. Error message

Basic usage​

Loading...
Edit live code
() => { // ignore - for live code example only.
  const Example = () => {
    const [date, setDate] = useState({ day: '', month: '', year: '' });

    return (
      <DateField
        id="dob"
        label="Date of birth"
        hint="For example, 21 7 1997"
        value={date}
        onChange={setDate}
      />
    );
  }

  return <Example />;
}

Variants and features​

Controlled and uncontrolled​

DateField accepts either value + onChange for controlled use, or defaultValue for uncontrolled use. The value type is { day: string; month: string; year: string }.

Controlled, with value and onChange. The parent owns the value, so the field shows whatever is in state:

Loading...
Edit live code
() => { // ignore - for live code example only.
  const Example = () => {
    const [date, setDate] = useState({ day: '21', month: '7', year: '1997' });

    return (
      <Stack spaceBetween={3}>
        <DateField
          id="dob-controlled"
          label="Date of birth"
          hint="For example, 21 7 1997"
          value={date}
          onChange={setDate}
        />
        <P>Current value: {date.day}/{date.month}/{date.year}</P>
      </Stack>
    );
  }

  return <Example />;
}

Uncontrolled, with defaultValue. The field manages its own value after the initial render:

Loading...
Edit live code
<DateField
  id="dob-uncontrolled"
  label="Date of birth"
  hint="For example, 21 7 1997"
  defaultValue={{ day: '21', month: '7', year: '1997' }}
/>

Read-only​

Use the readOnly prop to display a date that the user cannot edit.

Loading...
Edit live code
<DateField
  id="dob-readonly"
  label="Date of birth"
  readOnly
  defaultValue={{ day: '21', month: '7', year: '1997' }}
/>

Common form features​

The following features are shared across all Nebula form fields. See Form guidance for full detail.

Validation and errors: when a field is invalid, an error message appears below the inputs. DateField has no built-in date validation; validate the value in your own code before displaying an error.

Hint text: always include hint text showing the expected format: "For example, 21 7 1997". Accept both padded ("07") and unpadded ("7") values for day and month.

Required and optional: fields are required by default. Use the optional prop to mark a field as optional.

Field width: use fullWidth to control responsive behaviour. The default (small) makes the field full width below the smallest breakpoint and constrains it above. always keeps it full width at all breakpoints; never keeps it at its fixed width.