Calendar

The calendar lets users select a date from a month view.

When to use

  • The user needs to understand a date in relation to nearby days or weeks. They need to see a whole month at a time, compare days and weeks, and quickly understand which dates are available for their task.
  • The user needs to understand patterns over time in a logistics task, such as pickup availability or cutoff dates.
  • The layout needs the month grid itself for single date selection, rather than a field that opens one.

When not to use

  • If the user already knows the date and only needs to enter it, use Input date instead.
  • If the user needs to select a span of dates, such as a free-storage period, use Date range instead.

Usage guidance

Set up the calendar so users can see which dates they can choose, and why, before they select one.

Limit the selectable dates

Set a minimum selectable date, a maximum selectable date, or both to restrict which dates users can select. Use this when the context limits the date range to available dates, which prevents impossible selections. Limiting the range also reduces scrolling through months and speeds up decisions. Keep the selectable date range practical for the user journey. The product team should define it. For example, show booking dates from today onward for the next 6 months.

A shipper booking a pickup cannot choose a date in the past or more than 6 months ahead, which reduces error messages after submission.

The year cap sets how many years back and forward from the current year the year picker shows. The minimum and maximum dates disable the years outside the selectable range. Because the two work together, set the year cap wide enough that the year picker reaches the years of the minimum and maximum dates. The product team sets the year cap and the date range to suit the user journey and business context.

The year picker shows the years around the current one. Years outside the minimum and maximum dates are greyed out, so users can select only the available years.

Customise day styles

Style individual days or ranges, or disable them, to show availability, status, or special conditions. Use the styling consistently, so users learn the visual codes quickly.

  • Disable days for vacations and public holidays. These need no legend explanation.
  • Mark any other day whose meaning is not self-evident, such as a departure date, a cutoff date, a capacity limit, or a day that is unavailable for another reason and lies within the selectable range. Marking important days lets users recognise patterns at a glance instead of checking each date individually.
  • Explain every marker in the calendar footer as a legend, so users understand what it means, including why a day cannot be selected, where that applies.
  • Days outside the minimum and maximum dates need no marking.

Together, these styles make business rules visible up front, so users understand what is possible before they act, instead of discovering problems only after submitting a form.

A month with some days disabled, some days marked with a small coloured bar, and a footer legend that explains the marker. Users can quickly scan the month and choose viable dates without trial‑and‑error clicking, which reduces frustration and speeds up booking.

Show adjacent-month days when users read across month boundaries

Showing days from the previous and next month is optional. It helps when users read across week rows that span a month boundary, such as cutoffs or vessel schedules around month end, because blank leading and trailing cells hide the neighbouring days. It helps less when those days would compete visually with custom day styles or week numbers.

Show week numbers only for audiences that expect them

The calendar can optionally display week numbers in the leftmost column. Week numbers are mainly used in Europe and parts of Asia, where they follow the ISO‑8601 standard. They are not widely used in the U.S., Canada, Australia, or New Zealand.

Show week numbers only in regions, countries, and contexts where users expect them, for example European planning teams that refer to “week 14”.

Use when

  • The product serves regions where week‑based planning is standard.
  • Users coordinate across multiple tools or documents that reference week numbers (spreadsheets, transport plans, contracts).

Avoid when

  • The audience is global and not familiar with week numbers.
  • Week numbers would compete visually with other visual signals, such as custom day styles.
Showing week numbers for the right audiences reduces translation work (“week 5” vs “the week that starts on 25 January”) and fits existing planning workflows.

Patterns

Recurring compositions for the Calendar in a page layout.

Reserve vertical space for six weeks

When users navigate the calendar month to month, its height changes based on the number of weeks in each month. Make sure the UI has enough vertical space for six weeks, so the interface does not shift during month changes.

Leave enough vertical space in the page layout to accommodate a maximum of 6 visible weeks.

Accessibility

The calendar supports the expected keyboard and screen reader behaviours out of the box.

Input date and Date range both use the Calendar. It can also be used as the basis for custom date and time selection components and patterns.

ComponentUse case
Input dateWhen the user already knows the date and only needs to enter it
Date rangeWhen the user needs to select a span of dates, such as a free-storage period

See also