;
};
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
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 field | The input control people focus, type into, or use to open the calendar |
| **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.
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)
`}
>
```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. 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.
`}
>
```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 = previewRoot.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"}}
```
### 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`.
body {
padding: var(--bq-spacing-l);
}
`}
>
```js JavaScript icon="js" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
const datePickerElem = previewRoot.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"}}
```
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.
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 the internal `` 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
| 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)* | `Intl.DateTimeFormat` options used for the displayed value. When omitted, defaults are derived from `precision` (`day` → `{ day, month, year }`, `month` → `{ month, year }`, `year` → `{ year }`) | `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` | Placeholder text | `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 input value changes after typing, pasting, or selecting a date | `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` | Optional suffix content inside the control |
| `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` | Native input element |
| `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.
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.
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 field | The input control people focus, type into, or use to open the calendar |
| **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