Migrate from 2.x

3.x is a Vue 3 build of the same component. Every 2.x prop, event, slot, vfc-* class and value shape is still there. Most apps change a few lines.

The 3.0.0 release on npm was a Vue 2 build, so a ^3.0.0 range may resolve to it. Vue 2 apps pin ^2.10.0:

npm install vue-functional-calendar@^2.10.0

Steps

1. Upgrade to Vue ^3.3.0.
2. Install the package: npm install vue-functional-calendar@^3.1.0.
3. Import the stylesheet once: import 'vue-functional-calendar/style.css'.
4. Register the plugin with app.use.
5. Rename value and input if you use them without v-model.
6. Replace SCSS variable overrides with --vfc-* tokens.

v-model

value and input became modelValue and update:modelValue. A template that uses v-model needs no change.

<!-- 2.x and 3.x -->
<FunctionalCalendar v-model="calendarData" is-date-range />

<!-- 2.x, without v-model -->
<FunctionalCalendar :value="calendarData" @input="calendarData = $event" />

<!-- 3.x, without v-model -->
<FunctionalCalendar
  :model-value="calendarData"
  @update:model-value="calendarData = $event"
/>

The value object has the same shape: currentDate, selectedDate, selectedDateTime, selectedHour, selectedMinute, selectedDatesItem, selectedDates, dateRange and multipleDateRange.

Styles

The CSS is a separate file. Import it once.

import 'vue-functional-calendar/style.css'

Your 2.x CSS overrides keep working, because the vfc-* class names are unchanged. The default look changed, so check your overrides against it.

Vue 3 renamed the transition class -enter to -enter-from. An override of .vfc-calendar-slide-left-enter, -right-enter, -up-enter or -down-enter must now target .vfc-calendar-slide-left-enter-from and so on. The -enter-active, -leave-active and -leave-to classes keep their names.

Registration

Vue 2 used Vue.use. Vue 3 uses app.use, and the options still become global defaults.

// 2.x
Vue.use(FunctionalCalendar, { showWeekNumbers: true })

// 3.x
app.use(FunctionalCalendar, { showWeekNumbers: true })

Both import FunctionalCalendar from 'vue-functional-calendar' and import { FunctionalCalendar } from 'vue-functional-calendar' still work.

SCSS variables

The SCSS !default variables are gone. Custom properties replace them. Set a token on the calendar or on any ancestor, with plain CSS and no Sass.

.my-calendar {
  --vfc-primary: #e11d48;
  --vfc-on-primary: #ffffff;
}

The 2.x variables named colors, not roles, so the mapping below is by use. The old and new values do not match one to one.

$powderblue and $charade were never used. The full token list is in the theming guide.

Behavior changes

• Week numbers with sundayStart follow ISO numbering of each row's Thursday. 2.x showed numbers one lower.
• A typed date is validated. 31/02/2026 is rejected, and a value commits only when day, month and a four digit year are complete. Padded dates such as 05/03/2026 are accepted.
• Enter in the single and range inputs is never intercepted, so a surrounding form submits. The tags input of the multiple date picker still adds a valid typed date on Enter.

Imports

3.x has an exports map with two entries, vue-functional-calendar and vue-functional-calendar/style.css. Deep imports from src/ no longer resolve. Use the package entry.

// 2.x
import FunctionalCalendar from 'vue-functional-calendar/src/components/FunctionalCalendar.vue'

// 3.x
import { FunctionalCalendar } from 'vue-functional-calendar'

Most props are still read once

As in 2.x, the calendar reads most props once, when it is created. Re-key the component to apply a change:

<FunctionalCalendar :key="locale" :locale="locale" is-date-picker />

3.1 watches modelValue and the data props markedDates, markedDateRange, disabledDates, enabledDates, disabledDayNames, limits, calendarsCount and isDark, in configs too. Change them on a live calendar without a re-key. The same rule as before decides the source: when configs is present, the props are ignored.

New in 3.1

• Theming with --vfc-* tokens and a dark mode.
• Keyboard navigation and a grid with ARIA roles.
• The locale prop and the labels prop.
• The presets prop for quick ranges.

See the changelog for the full list.