Calendar - Vant 4
Calendar
📅 Time to pick the perfect date! Let's explore the Calendar component!
Intro 📖
Your ultimate date picker companion! Whether you need to select a single date, multiple dates, or date ranges, this Calendar component has got you covered! 🗓️ Perfect for booking systems, event planning, or any time-sensitive application! ⏰
Install 📦
Ready to schedule some dates? Register the component globally via app.use - it's that simple! 🎯 Check out our Component Registration guide for more installation options.
import { createApp } from'vue'; import { Calendar } from'vant'; const app = createApp(); app.use(Calendar);Usage 🎮
Select Switch Mode 🔄
Smart performance optimization! By default, all months are displayed in a beautiful tiled layout. For better performance with many months, enable the switch-mode prop to show navigation buttons! 🚀
Select Single Date 📅
Pick that perfect day! The confirm event fires when your date selection is complete - simple and straightforward! ✨
import { ref } from'vue'; exportdefault { setup() { const date = ref(''); const show = ref(false); constformatDate = (date) => { return`${date.getFullYear()}/${date.getMonth() + 1}/${date.getDate()}`; }; constonConfirm = (value) => { show.value = false; date.value = formatDate(value); }; return { date, show, onConfirm, }; }, };Select Multiple Date 📅📅
Why choose just one? Select multiple dates for events, holidays, or any multi-day planning! The more the merrier! 🎉
import { ref } from'vue'; exportdefault { setup() { const text = ref(''); const show = ref(false); constonConfirm = (dates) => { show.value = false; text.value = `${dates.length} dates selected`; }; return { text, show, onConfirm, }; }, };Select Date Range 📅➡️📅
Perfect for bookings and trips! Set type to range and select start and end dates. The confirm event returns an array with your start and end dates - planning made easy! 🗓️✈️
import { ref } from'vue'; exportdefault { setup() { const date = ref(''); const show = ref(false); constformatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`; constonConfirm = (values) => { const [start, end] = values; show.value = false; date.value = `${formatDate(start)} - ${formatDate(end)}`; }; return { date, show, onConfirm, }; }, };Quick Select ⚡
Need speed? Set show-confirm to false to skip the confirm button! The confirm event fires instantly when you make your selection - lightning fast! 🚀
Custom Color 🎨
Make it match your brand! Use the color prop to customize the calendar's theme color - your calendar, your style! 🌈
Custom Date Range 📊
Set boundaries that make sense! Use min-date and max-date to define available date ranges - perfect for booking systems and event planning! 🎯
import { ref } from'vue'; exportdefault { setup() { const show = ref(false); return { show, minDate: newDate(2010, 0, 1), maxDate: newDate(2010, 0, 31), }; }, };Custom Confirm Text 💬
Speak your users' language! Use confirm-text and confirm-disabled-text to customize button text - make it personal! ✨
Custom Day Text 📝
Add personality to your dates! Use the formatter function to customize day text, add holidays, events, or any special information! 🎊
exportdefault { setup() { constformatter = (day) => { const month = day.date.getMonth() + 1; const date = day.date.getDate(); if (month === 5) { if (date === 1) { day.topInfo = 'Labor Day'; } elseif (date === 4) { day.topInfo = 'Youth Day'; } elseif (date === 11) { day.text = 'Today'; } } if (day.type === 'start') { day.bottomInfo = 'In'; } elseif (day.type === 'end') { day.bottomInfo = 'Out'; } return day; }; return { formatter, }; }, };Custom Position 📍
Position it perfectly! Use position to control where your calendar appears - top, left, right, or bottom. Find the sweet spot! 🎯
Max Range 📏
Keep it reasonable! Use max-range to limit the number of selectable days in range mode - perfect for vacation policies or booking limits! 🏖️
Custom First Day Of Week 📅
Start your week your way! Use first-day-of-week to set whether your week starts on Sunday, Monday, or any day you prefer! 🌟
Tiled Display 🖼️
Go full-screen! Set poppable to false to display the calendar directly on the page instead of in a popup - perfect for dedicated calendar pages! 📱
API
Props
| Attribute | Description | Type | Default |
|---|---|---|---|
| type | Type, can be set to range``multiple | string | single |
switch-mode v4.9.0 | Switch mode:none Display all months in a tiled format without switch buttonsmonth Support switching by month, displaying buttons for previous month/next monthyear-month Support switching by year, as well as by month, displaying buttons for previous year/next year and previous month/next month | string | none |
| title | Title of calendar | string | Calendar |
| color | Color for the bottom button and selected date | string | #1989fa |
| min-date | Min date | Date | When switch-mode is set to none, the default value is the today | | max-date | Max date | Date | When switch-mode is set to none, the default value is six months after the today | | default-date | Default selected date | Date | Date[] | null | Today | | row-height | Row height | number | string | 64 | | formatter | Day formatter | (day: Day) => Day | - | | poppable | Whether to show the calendar inside a popup | boolean | true | | lazy-render | Whether to enable lazy render | boolean | true | | show-mark | Whether to show background month mark | boolean | true | | show-title | Whether to show title | boolean | true | | show-subtitle | Whether to show subtitle | boolean | true | | show-confirm | Whether to show confirm button | boolean | true | | readonly | Whether to be readonly | boolean | false | | confirm-text | Confirm button text | string | Confirm | | confirm-disabled-text | Confirm button text when disabled | string | Confirm | | first-day-of-week | Set the start day of week | 0-6 | 0 |
Calendar Poppable Props
Following props are supported when the poppable is true
| Attribute | Description | Type | Default |
|---|---|---|---|
| v-model:show | Whether to show calendar | boolean | false |
| position | Popup position, can be set to top``right``left | string | bottom |
| round | Whether to show round corner | boolean | true |
| close-on-popstate | Whether to close when popstate | boolean | true |
| close-on-click-overlay | Whether to close when overlay is clicked | boolean | true |
| safe-area-inset-top | Whether to enable top safe area adaptation | boolean | false |
| safe-area-inset-bottom | Whether to enable bottom safe area adaptation | boolean | true |
| teleport | Specifies a target element where Calendar will be mounted | *string | Element* |
Calendar Range Props
Following props are supported when the type is range
| Attribute | Description | Type | Default |
|---|---|---|---|
| max-range | Number of selectable days | *number | string* |
| range-prompt | Error message when exceeded max range | string | Choose no more than xx days |
| show-range-prompt | Whether prompt error message when exceeded max range | boolean | true |
| allow-same-day | Whether the start and end time of the range is allowed on the same day | boolean | false |
Calendar Multiple Props
Following props are supported when the type is multiple
| Attribute | Description | Type | Default |
|---|---|---|---|
| max-range | Max count of selectable days | *number | string* |
| range-prompt | Error message when exceeded max count | string | Choose no more than xx days |
Data Structure of Day
| Key | Description | Type |
|---|---|---|
| date | Date | Date |
| type | Type, can be set to selected��start��middle��end��disabled��start-end��multiple-selected��multiple-middle��placeholder | string |
| text | Text | string |
| topInfo | Top info | string |
| bottomInfo | Bottom info | string |
| className | Extra className | string |
Events
| Event | Description | Arguments |
|---|---|---|
| select | Emitted when date is selected | *value: Date |
| confirm | Emitted after date selection is complete, if show-confirm is true, it is Emitted after clicking the confirm button | *value: Date |
| open | Emitted when opening Popup | - |
| close | Emitted when closing Popup | - |
| opened | Emitted when Popup is opened | - |
| closed | Emitted when Popup is closed | - |
| unselect | Emitted when unselect date when type is multiple | value: Date |
| month-show | Emitted when a month enters the visible area (effective when switch mode is none) | value: { date: Date, title: string } |
| over-range | Emitted when exceeded max range | - |
| click-subtitle | Emitted when clicking the subtitle | event: MouseEvent |
click-disabled-date v4.7.0 | Emitted when clicking disabled date | *value: Date |
click-overlay v4.9.16 | Emitted when overlay is clicked | event: MouseEvent |
| panel-change | Emitted when switching calendar panel (effective when switch mode is not none) | { date: Date } |
Slots
| Name | Description | SlotProps |
|---|---|---|
| title | Custom title | - |
| subtitle | Custom subtitle | { text: string, date?: Date } |
month-title v4.0.9 | Custom title of every month | { text: string, date: Date } |
| footer | Custom footer | - |
| confirm-text | Custom confirm text | { disabled: boolean } |
| top-info | Custom top info of day | day: Day |
| bottom-info | Custom bottom info of day | day: Day |
| text | Custom text of day | day: Day |
| prev-month | Custom previous month button | { disabled: boolean } |
| prev-year | Custom previous year button | { disabled: boolean } |
| next-month | Custom next month button | { disabled: boolean } |
| next-year | Custom next year button | { disabled: boolean } |
Methods
Use ref to get Calendar instance and call instance methods.
| Name | Description | Attribute | Return value |
|---|---|---|---|
| reset | Reset selected date, will reset to default date when no params passed | *date?: Date | Date[]* |
| scrollToDate | Scroll to date | date: Date | - |
| getSelectedDate | get selected date | - | *Date |
Types
The component exports the following type definitions:
importtype { CalendarSwitchMode, CalendarType, CalendarProps, CalendarDayItem, CalendarDayType, CalendarInstance, } from'vant';CalendarInstance is the type of component instance:
import { ref } from'vue'; importtype { CalendarInstance } from'vant'; const calendarRef = ref<CalendarInstance>(); calendarRef.value?.reset();Theming
CSS Variables
The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.
| Name | Default Value | Description |
|---|---|---|
| --van-calendar-background | var(--van-background-2) | - |
| --van-calendar-popup-height | 80% | - |
| --van-calendar-header-shadow | 0 2px 10px rgba(125, 126, 128, 0.16) | - |
| --van-calendar-header-title-height | 44px | - |
| --van-calendar-header-title-font-size | var(--van-font-size-lg) | - |
| --van-calendar-header-subtitle-font-size | var(--van-font-size-md) | - |
| --van-calendar-header-action-width | 28px | - |
| --van-calendar-header-action-color | var(--van-text-color) | - |
| --van-calendar-header-action-disabled-color | var(--van-text-color-3) | - |
| --van-calendar-weekdays-height | 30px | - |
| --van-calendar-weekdays-font-size | var(--van-font-size-sm) | - |
| --van-calendar-month-title-font-size | var(--van-font-size-md) | - |
| --van-calendar-month-mark-color | fade(var(--van-gray-2), 80%) | - |
| --van-calendar-month-mark-font-size | 160px | - |
| --van-calendar-day-height | 64px | - |
| --van-calendar-day-font-size | var(--van-font-size-lg) | - |
| --van-calendar-day-margin-bottom | 4px | - |
| --van-calendar-day-disabled-color | var(--van-text-color-3) | - |
| --van-calendar-range-edge-color | var(--van-white) | - |
| --van-calendar-range-edge-background | var(--van-primary-color) | - |
| --van-calendar-range-middle-color | var(--van-primary-color) | - |
| --van-calendar-range-middle-background-opacity | 0.1 | - |
| --van-calendar-selected-day-size | 54px | - |
| --van-calendar-selected-day-color | var(--van-white) | - |
| --van-calendar-selected-day-background | var(--van-primary-color) | - |
| --van-calendar-info-font-size | var(--van-font-size-xs) | - |
| --van-calendar-info-line-height | var(--van-line-height-xs) | - |
| --van-calendar-confirm-button-height | 36px | - |
| --van-calendar-confirm-button-margin | 7px 0 | - |
FAQ
How to use asynchronously returned data in the 'formatter'?
If you need to use asynchronously returned data in a 'formatter', you can dynamically create a 'formatter' function using computed properties, as shown in the following example:
const asyncData = ref(); const formatter = computed(() => { if (!asyncData.value) { return(day) => day; } return(day) => { day.bottomInfo = asyncData.value; return day; }; }); setTimeout(() => { asyncData.value = 'text'; }, 3000);Failed to initialize components on iOS system?
If you encounter an issue where components cannot be rendered on iOS, please confirm that you did not use the new Date ('2020-01-01') notation when creating the Date object. iOS does not support date formats separated by a dash. The correct notation is new Date ('2020/01/01').
Detailed explanation of this issue: stackoverflow.
Alternatively, you should adopt a more compatible writing style across different systems and browsers: new Date (2020, 0, 1), but it should be noted that the month starts from 0.
Related Docs 📚
- DatePicker - Alternative date selection component
- TimePicker - Select time values
- Popup - Calendar popup container
- Button - Confirm and action buttons
- Field - Input field integration
- Form - Use calendar in forms
- ConfigProvider - Global configuration
- Advanced Usage - Component registration guide