UI Kit components
UI Kit hooks
Forge bridge APIs
Jira bridge APIs
Upgrade UI Kit versions
Previous versions

Date picker

To add the DatePicker component to your app:

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


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


appearance"default" | "subtle" | "none"NoSet the appearance of the picker. subtle will remove the borders, background, and icon.
autoFocusbooleanNoSet the picker to autofocus on mount.
defaultIsOpenbooleanNoThe default for isOpen. Will be false if not provided.
defaultValuestringNoThe default for value. This should be an ISO date.
disabledArray<string>NoAn array of ISO dates that should be disabled on the calendar. This does not affect what users can type into the picker.
maxDatestringNoThe latest enabled date. Dates after this are disabled on the calendar. This does not affect what users can type into the picker.
minDatestringNoThe earliest enabled date. Dates before this are disabled on the calendar. This does not affect what users can type into the picker.
idstringNoSets the ID of the field.
isDisabledbooleanNoSet if the picker is disabled.
isOpenbooleanNoSet if the picker is open.
namestringNoThe name of the field.
nextMonthLabelstringNoThe aria-label attribute associated with the next-month arrow. Defaults to "Next month".
onBlur(e: BlurEvent) => voidNoCalled when the field is blurred.
onChange(value: string) => voidNoCalled when the value changes. The only argument is an ISO time or empty string.
onFocus(e: FocusEvent) => voidNoCalled when the field is focused.
previousMonthLabelstringNoThe aria-label attribute associated with the previous-month arrow. Defaults to "Previous month".
spacing"default" | "compact"NoThe spacing for the select control.
valuestringNoThe ISO time used as the input value.
isInvalidbooleanNoSet if the picker has an invalid value.
dateFormatstringNoFormat the date with a string that is accepted by date-fn's format function. Note that this property only changes the displayed value, and that it does not affect the placeholder value nor the required format for manually-typed inputs.
placeholderstringNoPlaceholder text displayed in input.
localestringNoLocale used to format the date and calendar. See DateTimeFormat. Note that this affects the accepted format for the text input.
weekStartDay0 | 1 |2 | 3 | 4 | 5 | 6NoStart day of the week for the calendar.
0 Sunday (default value)
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday



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

Example image of a rendered date picker

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.


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

Example image of a validation message

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 (
      onSubmit={handleSubmit((values) => console.log("form submitted", values))}
        <Label labelFor={getFieldId("dateValue")}>
          Start day
          <RequiredAsterisk />
        <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>
        <Button type="submit">Submit</Button>

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.

Example image of a date picker with date range

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

const disabledDates = [

const DatePickerDisabledExample = () => (
    <Label labelFor="datepicker-disabled">Disabled Dates</Label>

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.

Example image of a date picker with date range

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

const DatePickerDisableRangeExample = () => (
    <Label labelFor="datepicker-disabled-range">Disabled Date Range</Label>


DatePicker supports internationalization through two props:

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


Use locale to tailor UI copy to local audiences.

Example image of a date picker with locale

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

const DatePickerLocaleExample = () => (
    <Label labelFor="datepicker-locale-en">English example</Label>
    <Label labelFor="datepicker-locale-jp">Japanese example</Label>

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.

Example image of a date picker with alternative start day

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

const DatePickerWeekStartDayExample = () => (
    <Label labelFor="datepicker-sunday">Week starting on Sunday</Label>
    <Label labelFor="datepicker-monday">Week starting on Monday</Label>

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.

Example image of a date picker with alternative date format

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

const DatePickerFormattingExample = () => (
    <Label labelFor="datepicker-format">Custom Date Format</Label>

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."

Rate this page: