;
};
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
Allows users to select a single date from a calendar interface. This type is useful for scenarios where only one date selection is required, such as booking appointments or scheduling events.
Allows users to choose a start and end date in one field. Use it for journeys, availability windows, and other consecutive periods.
## 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.
| Part | Element | Description |
| - | - | - |
| **1** | Label | Describes what date the field is asking for (`label` slot) |
| **2** | Date segments | The day, month, and year controls people focus and edit, ordered for the active locale |
| **3** | Icon | The calendar affordance that signals date selection and panel access |
| **4** | Calendar | The panel surface that contains the date selection interface |
| **5** | Month and year control | The heading and navigation controls used to move through months and years |
| **6** | Week day | The abbreviated day-of-week labels that structure the calendar grid |
| **7** | Day | An individual selectable calendar day |
| **8** | Selected date | The currently chosen day or days shown with selected styling |
| **9** | Current day | Today’s date, highlighted to help people orient themselves in the calendar |
## Design guidelines
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.
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.
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.
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
`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.
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
`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.
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
## 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.
body {
padding: var(--bq-spacing-l);
}
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class MonthPickerComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### 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.
body {
padding: var(--bq-spacing-l);
}
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class YearPickerComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### 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.
body {
padding: var(--bq-spacing-l);
}
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class DateOfBirthPickerComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Disabled
Use `disabled` when the date field should not be interactive, such as when access is restricted based on user permissions or form state.
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Validation states
Use `validation-status` when the field should show immediate visual feedback after validation.
:host {
justify-content: flex-start !important;
position: relative;
width: 100%;
z-index: 11;
}
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
<>
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### 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.
div[slot="label"] {
display: flex;
flex: 1 1 0%;
}
div[slot="label"] > label {
flex-grow: 1;
}
div[slot="label"] > span {
color: var(--bq-text--secondary);
}
Optional
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Label with info tooltip
Combine the label slot with a tooltip when users may need a short explanation before selecting a date.
:host {
min-height: 15rem !important;
}
bq-tooltip::part(trigger) {
display: flex;
}
label[slot="label"] {
display: flex;
flex-grow: 1;
align-items: center;
gap: 0.25rem;
}
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker, BqIcon, BqTooltip } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker, BqIcon, BqTooltip } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker, BqIcon, BqTooltip],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### Locale
Use `locale` to match date formatting and calendar conventions to regional expectations.
:host {
justify-content: flex-start !important;
position: relative;
width: 100%;
z-index: 11;
}
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### First day of week
Use `first-day-of-week` to align the calendar grid with regional or business expectations.
:host {
justify-content: flex-start !important;
position: relative;
width: 100%;
z-index: 11;
}
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### 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.
body {
padding: var(--bq-spacing-l);
}
`}
>
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
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.
body {
padding: var(--bq-spacing-l);
}
`}
>
```js JavaScript icon="js" theme={"theme":{"light":"one-light","dark":"night-owl"}}
const datePickerElem = document.querySelector('bq-date-picker[name="disallowed-dates"]');
const disallowedDates = ['2026-12-01', '2026-12-25', '2026-12-26'];
datePickerElem.isDateDisallowed = (date) => {
const dateString = date.toLocaleDateString('fr-CA');
return disallowedDates.includes(dateString);
};
```
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
const disallowedDates = ['2026-12-01', '2026-12-25', '2026-12-26'];
const isDateDisallowed = (date: Date) => {
const dateString = date.toLocaleDateString('fr-CA');
return disallowedDates.includes(dateString);
};
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {
disallowedDates = ['2026-12-01', '2026-12-25', '2026-12-26'];
isDateDisallowed = (date: Date): boolean => {
const dateString = date.toLocaleDateString('fr-CA');
return this.disallowedDates.includes(dateString);
};
}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
### 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.
body {
padding: var(--bq-spacing-l);
}
`}
>
```js JavaScript icon="js" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
const datePickerElem = document.querySelector('bq-date-picker[name="formatted-date"]');
datePickerElem.formatOptions = {
year: 'numeric',
month: 'numeric',
day: 'numeric',
};
```
```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqDatePicker } from "@beeq/react";
const formatOptions = {
year: 'numeric',
month: 'numeric',
day: 'numeric',
};
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqDatePicker],
template: `
`
})
export class AppComponent {
formatOptions: Intl.DateTimeFormatOptions = {
year: 'numeric',
month: 'numeric',
day: 'numeric',
};
}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
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.
body {
padding: var(--bq-spacing-l);
}
.date-form {
display: grid;
gap: var(--bq-spacing-m);
}
.date-form__actions {
display: flex;
gap: var(--bq-spacing-s);
justify-content: flex-end;
}
.date-form__output {
margin: 0;
padding: var(--bq-spacing-s);
border: var(--bq-stroke-s) solid var(--bq-stroke--tertiary);
border-radius: var(--bq-radius--s);
background: var(--bq-ui--secondary);
color: var(--bq-text--primary);
white-space: pre-wrap;
}
`}
>
```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { useState } from "react";
import { BqButton, BqDatePicker } from "@beeq/react";
export default function DatePickerForm() {
const [data, setData] = useState("{}");
return (
);
}
```
```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { Component } from "@angular/core";
import { BqButton, BqDatePicker } from "@beeq/angular/standalone";
@Component({
selector: "app-root",
standalone: true,
imports: [BqButton, BqDatePicker],
template: `
`,
})
export class DatePickerFormComponent {
data = "{}";
handleSubmit(event: SubmitEvent): void {
event.preventDefault();
this.data = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2);
}
}
```
```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
```
## Best practices
Do
Use clear, task-specific labels like "Arrival date" or "Travel dates" so users know exactly what they are selecting.
Don't
Do not overcomplicate the field label or ask for extra date information that the task does not need.
Do
Use a single combined input when possible. It keeps the interaction simpler and easier to scan.
Don't
Do not split day, month, and year into separate inputs unless the use case truly requires it.
Do
Disable unavailable dates when the business rules are known, instead of letting users submit invalid choices.
Don't
Do not rely on placeholder text as the only instruction or explanation for the field.
Do
Show two months for range selection when comparison matters, so people can understand the interval more easily.
Don't
Do 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
| Property | Attribute | Description | Type | Default |
| - | - | - | - | - |
| `autofocus` | `autofocus` | If `true`, the input is focused on component render | `boolean` | `false` |
| `calendarButtonLabel` | `calendar-button-label` | Accessible label for the calendar trigger button | `string` | `"Open calendar"` |
| `clearButtonLabel` | `clear-button-label` | Accessible label for the clear button | `string` | `"Clear value"` |
| `disableClear` | `disable-clear` | If `true`, the clear button is hidden | `boolean` | `false` |
| `disabled` | `disabled` | Disables the date picker | `boolean` | `false` |
| `distance` | `distance` | Gap between the panel and the input trigger | `number` | `8` |
| `firstDayOfWeek` | `first-day-of-week` | First day of the week where Sunday is `0` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` |
| `form` | `form` | ID of the form the input belongs to | `string` | `undefined` |
| `formValidationMessage` | `form-validation-message` | Native validation message used for required, invalid typed, and out-of-bounds values | `string` | `undefined` |
| `formatOptions` | *(property only)* | Numeric `Intl.DateTimeFormat` options that control segment order and separators. Textual or variable-length options fall back to the locale numeric layout with a development warning. | `DateTimeFormatOptions` | `undefined` |
| `initialView` | `initial-view` | Starting view when `precision` is `"day"`; month and year precision always open in their matching view | `"days" \| "months" \| "years"` | `"days"` |
| `isDateDisallowed` | *(property only)* | Function used to disable specific dates | `(date: Date) => boolean` | `undefined` |
| `locale` | `locale` | Locale used to format and parse dates | `Intl.LocalesArgument` | `"en-GB"` |
| `max` | `max` | Latest selectable date | `string` | `undefined` |
| `min` | `min` | Earliest selectable date | `string` | `undefined` |
| `months` | `months` | Number of months displayed for `range` and optionally `multi`, capped at `2` | `number` | `1` |
| `monthsPerView` | `months-per-view` | How navigation moves through months: one month or the full visible view | `"single" \| "months"` | `"single"` |
| `name` | `name` | Name of the underlying input | `string` | `undefined` |
| `open` | `open` | If `true`, the calendar panel is visible | `boolean` | `false` |
| `panelHeight` | `panel-height` | Overrides the panel height | `string` | `"auto"` |
| `placeholder` | `placeholder` | **Deprecated.** Locale-derived segment format hints always describe the expected entry layout, so this value no longer changes the rendered field. | `string` | `undefined` |
| `placement` | `placement` | Position of the calendar panel | `"top" \| "top-start" \| "top-end" \| "right" \| "right-start" \| "right-end" \| "bottom" \| "bottom-start" \| "bottom-end" \| "left" \| "left-start" \| "left-end"` | `"bottom-end"` |
| `precision` | `precision` | Granularity of the committed value (`day` → `YYYY-MM-DD`, `month` → `YYYY-MM`, `year` → `YYYY`) | `"day" \| "month" \| "year"` | `"day"` |
| `required` | `required` | Marks the date picker as required | `boolean` | `false` |
| `showOutsideDays` | `show-outside-days` | Shows days outside the current month | `boolean` | `false` |
| `skidding` | `skidding` | Horizontal offset between panel and trigger | `number` | `0` |
| `strategy` | `strategy` | Positioning strategy for the panel | `"fixed" \| "absolute"` | `"fixed"` |
| `type` | `type` | Selection mode | `"single" \| "range" \| "multi"` | `"single"` |
| `validationStatus` | `validation-status` | Validation state of the control | `"none" \| "error" \| "warning" \| "success"` | `"none"` |
| `value` | `value` | Selected value in the wire format matching `precision`; `range` uses `start/end`, `multi` uses space-separated dates | `string` | `undefined` |
### Events
| Event | Description | Type |
| - | - | - |
| `bqBlur` | Fired when the input loses focus | `CustomEvent` |
| `bqChange` | Fired when the value changes after segment entry or calendar selection | `CustomEvent<{ value: string \| undefined; el: HTMLBqDatePickerElement }>` |
| `bqClear` | Fired when the value is cleared | `CustomEvent` |
| `bqFocus` | Fired when the input receives focus | `CustomEvent` |
| `bqViewChange` | Fired when the calendar view switches between days/months/years | `CustomEvent<{ view: "days" \| "months" \| "years"; el: HTMLBqDatePickerElement }>` |
* 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
| Method | Description | Signature |
| - | - | - |
| `clear()` | Clears the selected value | `clear() => Promise` |
### Slots
| Slot | Description |
| - | - |
| `label` | Label content for the field |
| `prefix` | Optional prefix content inside the control |
| `suffix` | Replaces the icon inside the calendar trigger button; defaults to a calendar icon. Use `calendarButtonLabel` to name the button |
| `clear-icon` | Replaces the default clear icon |
### Shadow parts
| Part | Description |
| - | - |
| `base` | Base wrapper for the component |
| `label` | Label slot container |
| `control` | Input control wrapper |
| `prefix` | Prefix slot container |
| `suffix` | Suffix slot container |
| `input` | Segmented date field group |
| `segment` | Editable day, month, or year segment |
| `segment-literal` | Locale-derived separator between date segments |
| `clear-btn` | Clear button |
| `calendar-trigger` | Calendar icon trigger button |
| `button` | Any button rendered inside the calendar (nav or day/month/year cell) |
| `panel` | Dropdown panel container |
| `calendar__container` | Calendar panels wrapper |
| `calendar__header` | Header row (previous / title / next) |
| `calendar__heading` | Header title button (or month label above a panel) |
| `calendar__previous` | Previous navigation button |
| `calendar__next` | Next navigation button |
| `calendar__table` | Day-view `
` element |
| `calendar__head` | Day-view table header row wrapper |
| `calendar__tr` | Any row within the day-view table |
| `calendar__th` | Day-view weekday header cells |
| `calendar__week` | Body rows in the day-view table |
| `calendar__td` | Body cells in the day-view table |
| `calendar__day` | Any day button in the day view |
| `calendar__today` | Button representing today's date |
| `calendar__selected` | Any selected day |
| `calendar__outside` | Any day outside the visible month |
| `calendar__disallowed` | Any day rejected by `isDateDisallowed` |
| `calendar__disabled` | Any button disabled by min/max |
| `calendar__range-start` | First day of a range selection |
| `calendar__range-end` | Last day of a range selection |
| `calendar__range-inner` | Days between the start and end of a range |
| `calendar__months` | Month-view grid |
| `calendar__month` | Any month button |
| `calendar__month-selected` | Currently selected month |
| `calendar__years` | Year-view grid |
| `calendar__year` | Any year button |
| `calendar__year-selected` | Currently selected year |
### CSS custom properties
| Variable | Description | Default |
| - | - | - |
| `--bq-date-picker--background-color` | Input background color | `var(--bq-ui--primary)` |
| `--bq-date-picker--border-color` | Input border color | `var(--bq-stroke--tertiary)` |
| `--bq-date-picker--border-color-disabled` | Border color when disabled | `var(--bq-stroke--secondary)` |
| `--bq-date-picker--border-color-focus` | Border color on focus | `var(--bq-stroke--brand)` |
| `--bq-date-picker--border-radius` | Input border radius | `var(--bq-radius--s)` |
| `--bq-date-picker--border-style` | Border style | `solid` |
| `--bq-date-picker--border-width` | Border width | `1px` |
| `--bq-date-picker--currentDate-border-color` | Border color for today's date | `var(--bq-stroke--brand)` |
| `--bq-date-picker--currentDate-border-width` | Border width for today's date | `2px` |
| `--bq-date-picker--day-size` | Size of a day cell in the calendar | `2.25rem` |
| `--bq-date-picker--gap` | Gap between the input content and prefix/suffix | `var(--bq-spacing-xs)` |
| `--bq-date-picker--header-title-color` | Color of the per-panel month label in multi-panel view | `var(--bq-text--primary)` |
| `--bq-date-picker--icon-size` | Size of the icons used in prefix/suffix/clear | `1.5rem` |
| `--bq-date-picker--label-margin-bottom` | Space below the label | `var(--bq-spacing-xs)` |
| `--bq-date-picker--label-text-color` | Label text color | `var(--bq-text--primary)` |
| `--bq-date-picker--label-text-size` | Label text size | `0.875rem` |
| `--bq-date-picker--padding-end` | Input padding end | `var(--bq-spacing-m)` |
| `--bq-date-picker--padding-start` | Input padding start | `var(--bq-spacing-m)` |
| `--bq-date-picker--paddingY` | Input vertical padding | `var(--bq-spacing-s)` |
| `--bq-date-picker--range-background-color` | Background color for range start/end days | `var(--bq-ui--brand)` |
| `--bq-date-picker--range-inner-background-color` | Background color for inner range days | `var(--bq-ui--brand-alt)` |
| `--bq-date-picker--row-gap` | Vertical space between day-grid rows | `0.125rem` |
| `--bq-date-picker--text-color` | Input text color | `var(--bq-text--primary)` |
| `--bq-date-picker--text-placeholder-color` | Placeholder text color | `var(--bq-text--secondary)` |
| `--bq-date-picker--text-size` | Input text size | `1rem` |
| `--bq-date-picker--view-cell-background-hover` | Hover background for day/month/year cells | `var(--bq-ui--secondary)` |
| `--bq-date-picker--view-cell-background-selected` | Selected background for day/month/year cells | `var(--bq-ui--brand)` |
| `--bq-date-picker--view-cell-height` | Height of month/year cells | `2.75rem` |
| `--bq-date-picker--view-cell-radius` | Border radius of day/month/year cells | `0.5rem` |
| `--bq-date-picker--view-cell-text-selected` | Text color for selected day/month/year cells | `var(--bq-text--alt)` |
Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties).
## Resources
Explore date picker variants, validation, locale, and panel behavior in Storybook.
Browse the component implementation, styles, and tests on GitHub.
## Related topics
- [Changelog](/releases/changelog.md)
- [Input](/components/input.md)
- [Vue.js](/guides/frameworks/vue.md)
- [Dropdown](/components/dropdown.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
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.
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.
| Part | Element | Description |
| - | - | - |
| **1** | Label | Describes what date the field is asking for (`label` slot) |
| **2** | Date segments | The day, month, and year controls people focus and edit, ordered for the active locale |
| **3** | Icon | The calendar affordance that signals date selection and panel access |
| **4** | Calendar | The panel surface that contains the date selection interface |
| **5** | Month and year control | The heading and navigation controls used to move through months and years |
| **6** | Week day | The abbreviated day-of-week labels that structure the calendar grid |
| **7** | Day | An individual selectable calendar day |
| **8** | Selected date | The currently chosen day or days shown with selected styling |
| **9** | Current day | Today’s date, highlighted to help people orient themselves in the calendar |
## Design guidelines