Date picker

To add the DatePicker component to your app:

1
2
import { DatePicker } from '@forge/react';

Description

A date picker allows the user to select a particular date.

Props

Examples

Default

By default, selecting the date field opens the calendar view. The current date text is bold, underlined, and highlighted blue.

1
2
const DatePickerDefaultExample = () => (
  <>
    <Label labelFor="default-date-picker-example">Choose date</Label>
    <DatePicker id="default-date-picker-example" />
  </>
);

Field label and message

Always use a label component for each field and associate the label to the field properly. Use the HelperMessage component for any optional field-related message.

Required field label

For required fields, always add RequiredAsterisk component next to the label.

Validation

Use ErrorMessage or ValidationMessage components to display validation-related messages.

1
2
import React from "react";
import { Form, FormSection, FormFooter, Label, DatePicker, Button, ErrorMessage, ValidMessage, RequiredAsterisk } from "@forge/react";


export const DatePickerFormExample = () => {
  const { register, handleSubmit, formState, getFieldId } = useForm();
  return (
    <Form
      onSubmit={handleSubmit((values) => console.log("form submitted", values))}
    >
      <FormSection>
        <Label labelFor={getFieldId("dateValue")}>
          Start day
          <RequiredAsterisk />
        </Label>
        <DatePicker {...register("dateValue", { required: true })} />
        {formState.dirtyFields.dateValue && !formState.errors.dateValue && (
          <ValidMessage>You have entered a valid date</ValidMessage>
        )}
        {formState.errors.dateValue && (
          <ErrorMessage>This field is required</ErrorMessage>
        )}
      </FormSection>
      <FormFooter>
        <Button type="submit">Submit</Button>
      </FormFooter>
    </Form>
  );
};

Disabled dates

If a certain date is not a valid selection, you may disable it in the calendar shown to users. This does not restrict the dates that a user may type, so validation is necessary.

Specific dates

Use disabled to restrict selection of individual dates.

1
2
import { DatePicker, Label } from "@forge/react";

const disabledDates = [
  '2022-12-07',
  '2022-12-08',
  '2022-12-09',
  '2022-12-16',
  '2022-12-17',
  '2022-12-18',
];

const DatePickerDisabledExample = () => (
  <>
    <Label labelFor="datepicker-disabled">Disabled Dates</Label>
    <DatePicker
      defaultValue="2022-12-15"
      disabled={disabledDates}
      id="datepicker-disabled"
    />
  </>
);

Date ranges

Use minDate to set a minimum valid date and maxDate to set a maximum valid date. These can be used to define a valid date range.

1
2
import { DatePicker, Label } from "@forge/react";

const DatePickerDisableRangeExample = () => (
  <>
    <Label labelFor="datepicker-disabled-range">Disabled Date Range</Label>
    <DatePicker
      defaultValue="2020-12-15"
      minDate="2022-12-10"
      maxDate="2022-12-20"
      id="datepicker-disabled-range"
    />
  </>
);

Internationalization

DatePicker supports internationalization through two props:

• locale affects language, format and, parsing.
• weekStartDay determines the first day of the week shown on the calendar.

Locale

Use locale to tailor UI copy to local audiences.

1
2
import { DatePicker, Label } from "@forge/react";

const DatePickerLocaleExample = () => (
  <>
    <Label labelFor="datepicker-locale-en">English example</Label>
    <DatePicker
      locale="en-US"
      id="datepicker-locale-en"
    />
    <Label labelFor="datepicker-locale-jp">Japanese example</Label>
    <DatePicker
      locale="ja-JP"
      id="datepicker-locale-jp"
    />
  </>
);

export default DatePickerLocaleExample;

Week start day

Use weekStartDay to adjust which day of the week is shown first in the calendar. A value of 0 corresponds to Sunday (default), 1 to Monday, and so on.

1
2
import { DatePicker, Label } from "@forge/react";

const DatePickerWeekStartDayExample = () => (
  <>
    <Label labelFor="datepicker-sunday">Week starting on Sunday</Label>
    <DatePicker
      weekStartDay={0}
      id="datepicker-sunday"
    />
    <Label labelFor="datepicker-monday">Week starting on Monday</Label>
    <DatePicker
      weekStartDay={1}
      id="datepicker-monday"
    />
  </>
);

Date formats

You can customize the date format using the dateFormat prop. Formats are given as strings and use the syntax specified at Modern JavaScript date utility library.

Where possible, use locale for date formatting, instead of a custom format. Date formats should be informed by the user’s locale and the use case.

1
2
import { DatePicker, Label } from "@forge/react";

const DatePickerFormattingExample = () => (
  <>
    <Label labelFor="datepicker-format">Custom Date Format</Label>
    <DatePicker
      dateFormat="YYYY-MM-DD"
      placeholder="2021-06-10"
      id="datepicker-format"
    />
  </>
);

Accessibility considerations

When using the DatePicker component, we recommend keeping the following accessibility considerations in mind:

• Ensure that locale is appropriately set so that users see dates in a familiar format.
• Use a concise label to indicate what the date selection refers to.
• Allow multiple modes of data entry. Some users prefer entering date and time information by typing instead of selection, especially keyboard users.
• If some dates are disabled, provide accurate validation and error messaging for keyboard users, like "Please enter a future date."