Skip to main content
BEEQ Date-picker component overviewBEEQ Date-picker component overview

Date-picker component overview

Date pickers combine a calendar with locale-ordered day, month, and year segments. They reduce ambiguity, prevent formatting mistakes, and support single dates, ranges, and multiple dates.
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 anatomyBEEQ 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.
All selection types use locale-ordered numeric segments. A format hint shows the expected layout before entry starts; for locale="en-GB", day precision uses dd/mm/yyyy, month precision uses mm/yyyy, and year precision uses yyyy. Ranges and multiple dates render separate segment groups.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.The locale-derived format hint is always shown before entry starts. On focus, one segment is active. Type digits to replace that segment, use ArrowLeft and ArrowRight to move, Home and End to reach a group boundary, ArrowUp and ArrowDown to change a value, and Backspace or Delete to clear a segment. Paste is not supported.
type="single" is the default. range and multi use the same segmented-entry model, so users can type digits or choose dates from the calendar in every selection mode.

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

​
Segment layout

Use numeric formatOptions to set the segment order and separators. The component supports numeric or 2-digit day/month fields with a numeric year. This does not affect the underlying ISO wire value.
Textual or variable-length options such as month: 'long', weekday, and dateStyle cannot define a numeric segment layout. The component falls back to the locale’s numeric layout and logs a development warning.

​
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.
A non-empty incomplete segment draft becomes invalid when focus leaves the segmented field, even when the picker is optional. The draft stays visible and the last committed value is preserved, but native form validation blocks submission until you complete a valid date, choose a valid calendar date, or clear the field.
When focus leaves the segmented field, complete dates outside min or max are clamped to the nearest bound. Complete inverted ranges are displayed in chronological order. Invalid or incomplete drafts are not generally reverted to the previous displayed date.

​
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 its segmented date field when the component receives focus.
  • The segmented field is a labelled group; each day, month, and year control is a spinbutton with localized limits, value text, and roving tabindex. Range endpoints and multi-date groups have their own accessible labels.
  • The segmented field sets aria-disabled="true" when disabled is true. Each segment sets aria-invalid="true" for validationStatus="error" and native constraint failures such as required, invalid, or out-of-bounds values.
  • 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 announces a completed selection when focus enters the field, after a calendar selection, and announces the current calendar month, year, or year range after previous/next navigation.
  • Press Alt+ArrowDown, or Tab to the calendar icon and press Enter or Space, to open the panel. Calendar-trigger activation moves focus into its active date cell; the arrow keys navigate calendar cells and Escape closes the panel.
  • Clicking the segmented field opens the calendar while keeping segment focus. Clicking the calendar icon opens the panel and moves focus into it. Selecting a value from the panel returns focus to the first segment.
  • Opening the calendar closes any other open date picker, select, or dropdown panel, so only one panel stays open at a time.
  • Calendar days and months expose localized full names to assistive technology. Always provide a visible label through the label slot so the field and calendar dialog have a programmatic 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.