DatePicker

Anatomy

Guidelines

When to use

DatePicker allows users to select a specific date, range of dates, or a date and time from a dropdown calendar. Use a DatePicker when the value is a point or period on the calendar, such as a send date, a scheduled time, or the period a report covers.

DatePickers are most commonly used to filter reports and activity by date range, where presets offer quick access to common periods. They also schedule sends and set the timestamp a condition compares against.

Best practices

Date limits

Limit the calendar to the dates the user can actually choose. Dates outside the limits are disabled, which prevents an invalid selection instead of reporting it after the fact. Reporting filters, for example, rarely need dates after the current date.

Labels and placeholders

While not explicitly required, we highly recommend providing a visible label so users understand what the date represents. A DatePicker that filters a report usually sits in a toolbar, where a visible label competes with the controls around it. In those placements, provide an accessible label in place of a visible label.

Ranges

Use a single range DatePicker when the user needs both a start and an end date. One field keeps the period together, shows both ends in the same calendar, and prevents an end date that falls before the start. Reserve separate DatePickers for filters where either end is optional.

Customization

In adhering with Pluma's focus on flexibility, the DatePicker component includes customization options beyond plain text. Customization is useful for adding richer label content, building custom assistive text, or tailoring the presets to the data on the page.

Custom description

Descriptions are assistive text that display below the field. They can accept rich content including links.

Custom error

Error messages are assistive text that display below the field. They accept rich content, allowing the inclusion of links or formatted text that better help users resolve the issue.

Custom label

The label accepts rich content, allowing supplementary elements such as optional indicators alongside the label text.

Custom presets

Range types can replace the default presets with a list that matches the data on the page. Each preset can include an icon and a tooltip to explain what the period covers or why it's unavailable.

Types

Appearance

Presets

Range types can show a list of presets beside the calendar for common periods, such as the last 7 or 30 days. Show presets wherever users return to the same, consistent periods often. Time ranges also include shorter periods, such as the last hour.

Sizes

DatePickers are available in two sizes, medium and small. Medium is the default.

Behaviors

States

Clear button

A clear button can be enabled to reset the selection. Enable it when an empty field is a valid choice, such as an optional filter that shows all dates when cleared. The button is hidden when the field is empty.

Date limits

A DatePicker can set the earliest and latest dates the user can choose, or disable individual dates. Disabled dates can't be selected in the calendar, and presets whose period falls outside the limits are disabled as well.

Opening and closing

The popover opens when the field is clicked or receives focus, or when the user presses Down Arrow, Enter, or Space. Pressing Escape or clicking outside the popover closes it without changing the value.

Date and date range types apply the selection and close as soon as the user picks a day, the end of a range, or a preset. Time types hold the selection until the user saves it, so the date, time, and time zone can be adjusted together before the field updates.

Range length

Range types can require a minimum or maximum length. For date ranges, days that would make the range too short or too long are disabled once the start date is chosen. For time ranges, an error explains the limit and saving is unavailable until the range fits.

Time zones

Time types include a time zone selector, which defaults to the user's local time zone. Changing the time zone keeps the chosen time on the clock and moves the moment it represents. Unix timestamps can also be entered.

Content

Assistive text

Assistive text displays below the DatePicker and gives the user information about the date they're choosing. Assistive text comes in different forms including descriptions and error text.

Description

Use description text to explain how the date is used or what limits apply to it. Use short, complete sentences.

Error

Error messages communicate issues the user must resolve before submission. Frame errors as direct instructions that name the dates the user can choose instead. Keep messages direct and concise. Avoid using "Please".

Labels

Write clear, concise labels that describe what the date represents, not that it's a date. Use nouns and noun phrases.

Placeholders

Placeholders help the user complete a field by describing what information it expects. For the DatePicker, we recommend short phrases such as "Choose a date" or "Select a range". When the field is optional, the placeholder can describe what an empty field means instead.

Presets

Preset labels name the period relative to today. Keep labels parallel so the list scans as a set, and order them from the shortest period to the longest.