DatePicker
A control for selecting or inputting dates. It supports selection by day, week, month, year, quarter, and range, featuring exceptional aesthetic design and smooth interaction.
Showcase
DatePicker supports multiple units of panel display directly, which is common for custom layouts or dashboards.
Basic Usage
With the type attribute, you can quickly switch between date, month, and year selection modes.
Advanced Configuration
DatePicker provides rich attributes to meet fine-tuned customization needs, such as custom icons and special display formats.
Cell Shape
The appearance style supports not only the modern round (default) but also the classic and stable square.
Custom Cell Content
Through the cell-render attribute or date-cell slot, you can customize the display content of date cells, such as adding lunar calendars, holidays, solar terms, or business markers.
Disabled and Readonly
Use the disabled attribute to disable the component, and use the readonly attribute to set it to read-only.
Sizes
The component provides three sizes: large, default, and small, to adapt to different page spaces.
Presets
Through the presets attribute, quick selection options can be configured, greatly improving user selection efficiency.
Disabled Dates
Through the disabled-date function, you can customize which dates should not be selectable.
Range Selection
Set type to *range to enable range selection mode.
Use in Nuxt
DatePicker perfectly supports SSR rendering in Nuxt 3/4. In Nuxt projects, the component and its dependencies (styles, Hooks) are automatically imported, no manual registration required.
SSR Note
DatePicker has been optimized for Hydration internally, ensuring that the DOM structure generated on the server and client is completely consistent in SSR scenarios.
API
Props
| Prop | Description | Type | Default |
|---|---|---|---|
| v-model / model-value | Binding value | Date | string | number | Array | — |
| type | Display type | DatePickerType | 'date' |
| cell-shape | Cell shape | 'round' | 'square' | 'round' |
| disabled | Whether disabled | boolean | false |
| readonly | Whether readonly | boolean | false |
| clearable | Whether to show clear button | boolean | true |
| size | Size | 'large' | 'default' | 'small' | 'default' |
| placeholder | Placeholder when not in range mode | string | 'Please select date' |
| start-placeholder | Placeholder for start date in range mode | string | 'Start date' |
| end-placeholder | Placeholder for end date in range mode | string | 'End date' |
| format | Format displayed in the input box | string | — |
| value-format | Format of the binding value | string | — |
| date-format | Date format displayed on the panel | string | 'YYYY-MM-DD' |
| time-format | Time format displayed on the panel | string | 'HH:mm:ss' |
| range-separator | Separator when choosing range | string | '-' |
| first-day-of-week | First day of week (1-7) | number | 7 |
| disabled-date | Disabled dates function | (date: Date) => boolean | — |
| presets | Quick options | DatePickerPreset[] | [] |
| preset-position | Position of quick options | 'left' | 'right' | 'top' | 'bottom' | 'bottom' |
| show-footer | Whether to show operation bar at bottom | boolean | true |
| status | Input box status | 'success' | 'warning' | 'error' | — |
| order-on-confirm | Whether to auto-sort during range selection | boolean | false |
| prefix-icon | Custom prefix icon | string | Component | — |
| clear-icon | Custom clear icon | string | Component | — |
| default-value | Date shown by default when opening the picker | Date | Date[] | — |
| default-time | Default time (in datetime mode) | Date | Date[] | — |
| panel-only | Whether to display inline (panel only) | boolean | false |
| cell-render | Custom cell rendering function | (date: Date) => string | { text: string; className?: string } | — |
| teleported | Whether to insert the panel into body | boolean | true |
| popper-class | Popover class name | string | — |
| validate-event | Whether to trigger form validation | boolean | true |
Events
| Event Name | Description | Parameters |
|---|---|---|
| update:modelValue | Triggered when binding value is updated | (value: DateValue | DateRangeValue) => void |
| change | Triggered when value changes | (value: DateValue | DateRangeValue) => void |
| focus | Triggered on focus | (event: FocusEvent) => void |
| blur | Triggered on blur | (event: FocusEvent) => void |
| clear | Triggered when clear button is clicked | () => void |
| confirm | Triggered when confirm button is clicked | (value: DateValue | DateRangeValue) => void |
| panel-change | Triggered when panel view switches | (value: Date, mode: PanelView) => void |
| visible-change | Triggered when panel visibility changes | (visible: boolean) => void |
Slots
| Slot Name | Description |
|---|---|
| prefix-icon | Custom input prefix icon |
| clear-icon | Custom clear icon |
| extra | Extra content in the panel |
| date-cell | Custom date cell (Scope: { cell: CalendarCell }) |
| footer | Custom footer area |
Theme Variables
All color variables are connected to the global theme system and automatically support dark mode:
| Variable | Description | Default |
|---|---|---|
--yh-date-picker-width | Regular input box width | 220px |
--yh-date-picker-range-width | Range input box width | 400px |
--yh-date-picker-primary | Main theme color | var(--yh-color-primary) |
--yh-date-picker-text-main | Main text color | var(--yh-text-color-primary) |
--yh-date-picker-text-secondary | Secondary text color | var(--yh-text-color-secondary) |
--yh-date-picker-border | Border color | var(--yh-border-color) |
--yh-date-picker-panel-width | Panel physical width | 380px |
--yh-date-picker-panel-bg | Panel background color | var(--yh-bg-color-overlay) |
--yh-date-picker-panel-shadow | Panel shadow | var(--yh-shadow-lg) |
--yh-date-picker-item-hover | Hover background color | var(--yh-fill-color-light) |
--yh-date-picker-range-bg | Range background color | var(--yh-color-primary-light-9) |