Skip to main content
BEEQ Date-picker component overview

Date-picker component overview

Date pickers provide a guided way to enter dates through a calendar interface. They reduce ambiguity, prevent formatting mistakes, and make it easier to choose a single date, a range, or multiple dates depending on the task.
Use a date picker when the interface benefits from visual date selection or date validation. If users need to enter very flexible freeform dates or work with a tiny, predictable set of choices, a simpler input or select may be more appropriate.

​
When to use

Use date pickers when
  • Users need to select a specific date with high accuracy
  • A calendar view makes the choice faster than typing
  • You need to limit dates with min/max rules or disabled dates
  • The task involves travel dates, appointments, deadlines, or availability

Do not use date pickers when
  • The date can be entered more efficiently with a simple text field
  • The range of valid dates is so small that a select or radio group is clearer
  • Users need to enter partial, approximate, or highly flexible date values
  • The interaction would be unnecessarily heavy for the task

​
Patterns

​
Anatomy

BEEQ Date-picker component anatomy

Date-picker component anatomy

The date picker combines a labeled field with a calendar surface that helps people choose dates accurately. Keep the field label clear, make the calendar easy to scan, and ensure the selected format matches local expectations.

​
Design guidelines

1

Choose the simplest selection mode

Start with single when one date is enough. Use range only when people need both a start and end date, and use multi only for truly non-consecutive selections.
2

Keep labels and format expectations clear

Write labels that describe the task directly, such as “Arrival date” or “Travel dates”. Make sure the displayed format and first day of week match the product locale.
3

Use calendar rules to prevent bad choices

Apply min, max, isDateDisallowed, and validation states when business rules are known, so people are guided before they submit the form.
For range and most multi scenarios, showing two months at once usually makes comparison easier and reduces selection errors.
Use the calendar trigger to make date selection recognisable before people interact with the field.

​
Usage

​
Default

Use the default single type when users need to choose one date. This is the best starting point for appointments, due dates, deadlines, and similar tasks.
Users can also enter a date manually. After pressing Tab, the component formats the value and reflects it in the calendar view.The wire format of the value attribute — and of min/max — depends on precision: day uses YYYY-MM-DD, month uses YYYY-MM, and year uses YYYY. For type="range" two tokens are joined with / (start/end); for type="multi" tokens are space-separated.Supported input formats include:
  • ISO format: 2024-05-30
  • Text format: 30 May 2024, May 30, 2024, 30 January 2024, January 1, 1970 (locale-aware)
  • Numeric format: 30/05/2024, 05-30-2024, 30.05.2024, 05.30.2024 (with day/month heuristics)
type="single" is the default. Unlike range and multi, the single-date picker also supports manual typing with locale-aware parsing.

​
Date range

Use type="range" when users need a start and end date. Set months="2" so both months are visible in the panel and months-per-view="months" so navigation advances the full visible range.
months supports one or two panels. Two months make range comparison easier; use months-per-view="months" when each navigation action should advance both visible panels.

​
Multiple dates

Use type="multi" when users need to pick several non-consecutive dates. Unlike the single-date picker, the panel stays open while users continue selecting.

​
Options

​
Month selection

Use precision="month" when the task needs a month rather than a specific day, such as choosing a billing cycle. Month precision stores values as YYYY-MM and opens directly in the month view.

​
Year selection

Use precision="year" when users choose a whole year, such as a graduation year. Year precision stores values as YYYY and opens directly in the year view.

​
Calendar starting view

Use initial-view with day precision when people need to start their search from months or years. The picker still stores a full YYYY-MM-DD value after users complete the selection.

​
Disabled

Use disabled when the date field should not be interactive, such as when access is restricted based on user permissions or form state.

​
Validation states

Use validation-status when the field should show immediate visual feedback after validation.

​
Label with optional text

Use an optional indicator when the date adds context but is not required to complete the form.
You are responsible for the layout, styling, and accessibility of any custom content placed in the label slot.

​
Label with info tooltip

Combine the label slot with a tooltip when users may need a short explanation before selecting a date.

​
Locale

Use locale to match date formatting and calendar conventions to regional expectations.

​
First day of week

Use first-day-of-week to align the calendar grid with regional or business expectations.

​
Show outside days

By default, the calendar shows only the days of the displayed month. Enable show-outside-days when the additional context is helpful.
Avoid show-outside-days for range and multi unless the added density clearly improves the task. It can make complex selection states harder to read.

​
Disallowed dates

Use isDateDisallowed to make specific dates unavailable for selection. This is useful for holidays, sold-out inventory, blackout periods, or policy restrictions.

​
Custom display format

Use formatOptions to customize the display format of the selected date in the input field. This does not affect the underlying value, which is always stored as YYYY-MM-DD.
Use formatOptions carefully with range and multi. Long formats such as weekday: 'long' can produce unwieldy display values when multiple dates appear in the input field.

​
Form integration

bq-date-picker submits its current date value with the form. Use required and form-validation-message when the date is mandatory; the custom message also applies to invalid typed values and out-of-bounds dates.

​
Best practices

DoUse clear, task-specific labels like “Arrival date” or “Travel dates” so users know exactly what they are selecting.

Don’tDo not overcomplicate the field label or ask for extra date information that the task does not need.

DoUse a single combined input when possible. It keeps the interaction simpler and easier to scan.

Don’tDo not split day, month, and year into separate inputs unless the use case truly requires it.

DoDisable unavailable dates when the business rules are known, instead of letting users submit invalid choices.

Don’tDo not rely on placeholder text as the only instruction or explanation for the field.

DoShow two months for range selection when comparison matters, so people can understand the interval more easily.

Don’tDo not use a heavier multi-date or range pattern when one simple date field would solve the task.

​
Accessibility

  • bq-date-picker is form-associated and delegates focus, so it participates in native forms and moves focus into the internal <input> element when the component receives focus.
  • The input element sets aria-disabled="true" when disabled is true. It sets aria-invalid="true" for validationStatus="error" and native constraint failures such as required, invalid, or out-of-bounds values.
  • The input uses aria-haspopup="dialog" and aria-controls to announce the calendar panel. A label slot supplies aria-labelledby for both the input and calendar panel.
  • The calendar panel carries role="dialog" and is labelled via aria-labelledby when a label is present, or by its built-in “Date picker” label otherwise. The panel is not modal.
  • The component emits bqFocus, bqBlur, bqChange, and bqClear, which give you the hooks needed to announce validation results, react to changes, and keep form state synchronized.
  • Keyboard users can open the calendar panel with Enter or Space, navigate days with the arrow keys, and close the panel with Escape.
  • Always provide a visible label through the label slot. Without it, the input has no programmatic label, so nearby context must provide an equivalent accessible name.
  • Validation states should never rely on color alone. Pair validationStatus with visible error text so screen reader users receive the same feedback as sighted users.
  • Keep locale, first-day-of-week, and display formatting aligned with user expectations so typed input and visible values remain understandable for all users.

​
API reference

​
Properties

​
Events

  • In React, prefix events with on: onBqBlur, onBqChange, onBqClear, onBqFocus, onBqViewChange.
  • In Angular, use the event binding syntax: (bqBlur), (bqChange), (bqClear), (bqFocus), (bqViewChange).
  • In Vue, use the @ shorthand: @bqBlur, @bqChange, @bqClear, @bqFocus, @bqViewChange.

​
Methods

​
Slots

​
Shadow parts

​
CSS custom properties

Learn more about styling with shadow parts and CSS custom properties.

​
Resources

Interactive playground

Explore date picker variants, validation, locale, and panel behavior in Storybook.

Source code

Browse the component implementation, styles, and tests on GitHub.