Skip to content
lab components / Actions and controls

Date picker

Enable users to select a single date from a visual calendar interface.

ExamplesPropertiesGuidelinesNotable Changes

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { DatePicker } from "@siteimprove/fancylab";
ComponentsPurposeUsage guideline
Date Picker ComponentProvide a highly customizable date picker that seamlessly integrates with the application's design and functionality.Consider when customization, advanced features, specific user interactions, or complex data handling are crucial.
Browser-owned Date Picker Offer a familiar, accessible, and cross-browser compatible date picker with minimal development effort.Recommended for most use cases involving basic date selection where extensive customization and advanced features are not required.

#Examples

Date pickers simplify date input, making it especially useful for scheduling reports or filtering data. They offer a user-friendly alternative to manual text entry, reducing errors and ensuring consistent formatting.

The Date picker consists of:

  • Calendar view: A visual representation of a month or multiple months, allowing users to navigate and select a date.
  • Navigation controls: Arrows or buttons to move between months or years.
  • Today button: Quickly selects the current date.

#Basic usage

Sun
Mon
Tue
Wed
Thu
Fri
Sat
const [value, setValue] = useState(new Date(2000, 1, 1)); return ( <DatePicker value={value} onChange={(d) => setValue(d as Date)} translations={translations} /> );

#Properties

#DatePicker

Sun
Mon
Tue
Wed
Thu
Fri
Sat
PropertyDescriptionDefinedValue
valueRequired
| date | date[]Selected value
onChangeRequired
functionCallback for updating the value
translationsRequired
objectTranslation keys
minDateOptional
dateMin for date range
maxDateOptional
dateMax for date range
tileClassNameOptional
| string | string[] | function
minDetailOptional
"century" | "decade" | "month" | "year"
showNeighboringMonthOptional
boolean

#Guidelines

#Best practices

#General

Use DatePicker when

  • Users need to select a specific date.
  • Precise date input is required, reducing ambiguity.
  • The application requires a consistent date format.

#Placement

DatePicker is typically used in the following places:

#Style

  • Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your DatePicker to existing components for visual consistency.
  • Since the DatePicker doesn't have a built-in input field, always pair it with an Input Field component to display the selected date and trigger the calendar view. Ensure a clear visual connection between the selected dates in the calendar and the Input Field's display for a seamless user experience.
  • Use the Form element wrapper component to restrict date selections and display clear error messages for invalid choices (e.g., future dates).
  • Date formats can be customized and often vary based on user location. To avoid confusion, select a single date format and use it consistently throughout your interface.

#Do not use when

  • Users need to input a range of dates. Use Period Picker instead.
  • The application requires flexible date formats or natural language input.

#Accessibility

For designers

  • Clear labels and instructions.

For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Labels: Keep labels clear and concise (e.g., "Select Date").
  • Placeholder: Use a format example as the placeholder (e.g., "MM/DD/YYYY").
  • Helper text: Briefly explain interaction options (e.g., "Click calendar or type directly into this field").
  • Error messages: Clearly state the issue and expected format (e.g., "Invalid date. Use MM/DD/YYYY").

#Notable Changes

#Version 69.0.0

The DatePickerWithInput component has been removed. Use Input Field with type="date" instead.