DOCSEARCHbyAlgolia
Submit Docs

VueDatePicker Documentation

website·Indexed 32 days ago

https://vue3datepicker.com

A powerful datepicker component for Vue 3.5+ featuring multiple modes such as range, various pickers, and multiple calendars. The documentation covers installation, general configuration, validation, formatting, localization, timezone settings, and extensive customization via slots and CSS variables for theming.

Tokens
21.8K
Snippets
133
Records
143
Agent score
65%

What's inside VueDatePicker

  1. Migrate VueDatePicker flow control from v13

    When migrating from v13, several breaking changes affect how the date picker flow is handled. The handleFlow method has been renamed to executeFlow and now accepts a PickerSection step value instead of a numeric index. Additionally, the @flow-step event now emits the step value instead of the step index. The partial property within the flow prop has been removed as it no longer affects behavior.
    <template>
  <VueDatePicker
    ref="dpRef"
    :flow="{
      steps: ['year', 'month', 'calendar'],
      // partial: true, // REMOVE: This property is no longer used
    }"
    @flow-step="onFlowStep"
  />
</template>

<script lang="ts" setup>
  import { ref } from 'vue';
  import { VueDatePicker, type PickerSection } from '@vuepic/vue-datepicker';

  const dpRef = ref();

  // v13: dpRef.value?.handleFlow(1); 
  // v14+: Use executeFlow with the step value
  dpRef.value?.executeFlow('month'); 

  // v13: function onFlowStep(stepIndex: number) {}
  // v14+: Event now provides the PickerSection value
  function onFlowStep(step: PickerSection) {}
</script>

  2. Retrieve date values in the configured timezone

    When using the timezone prop, the v-model value is a TZDate object. There is a critical difference between logging the object and calling its toString() method:

    1. console.log(date): Displays the date as a standard Date object in the local browser timezone.
    2. date.toString(): Returns the date value in the configured timezone.

    To programmatically retrieve the date value in the specified timezone, you must call .toString() on the model value.

    import { ref, watch } from "vue";

const date = ref(new TZDate('Sat Oct 25 2025 19:28:21 GMT+0200 (Central European Summer Time)', 'utc'));

watch(date, (value) => {
    // Local timezone output
    console.log(value); 
    // Configured timezone output (e.g., UTC)
    console.log(value.toString()); 
})

  3. Customize Vue3 Datepicker themes using CSS variables

    The Datepicker supports theming via CSS variables. You can override the default theme by declaring the corresponding theme class in a global or scoped <style> tag. To enable the dark theme, the dark prop must be set to true on the component.

  4. Customize overlay headers for date and time pickers

    You can add custom content to the headers of various selection overlays using specific slot names. Each of these slots provides a toggle function that can be used to close the overlay (e.g., for a 'Go back' button).

    Available header slots:

    • #month-overlay-header: Header for the month selection overlay.
    • #year-overlay-header: Header for the year selection overlay.
    • #hours-overlay-header: Header for the hours selection overlay.
    • #minutes-overlay-header: Header for the minutes selection overlay.
    • #seconds-overlay-header: Header for the seconds selection overlay (requires :time-config="{ enableSeconds: true }").
    <template>
  <VueDatePicker v-model="date" :time-config="{ enableSeconds: true }">
    <!-- Example: Month Overlay Header -->
    <template #month-overlay-header="{ toggle }">
      <div>
        <span @click="toggle"> < Go back </span>
      </div>
    </template>

    <!-- Example: Seconds Overlay Header -->
    <template #seconds-overlay-header="{ toggle }">
      <div>
        <span>Seconds</span>
      </div>
    </template>
  </VueDatePicker>
</template>

<script lang="ts" setup>
  import { VueDatePicker } from '@vuepic/vue-datepicker';
  import { ref } from 'vue';
  const date = ref();
</script>

  5. Install @vuepic/vue-datepicker

    Install the Vue Datepicker component using a package manager. Note that the minimum supported version of vue is 3.5. The library only provides es bundles; compat mode, umd, and iife builds are not supported in version 12.0+.
    # npm
npm install @vuepic/vue-datepicker

# yarn
yarn add @vuepic/vue-datepicker

# pnpm
pnpm add @vuepic/vue-datepicker

# bun
bun add @vuepic/vue-datepicker

  6. Configure v-model data types for different picker modes

    Depending on the mode of the VueDatePicker, the model-value must follow these type requirements:

    • Date Picker: Single: Date | Range: [Date, Date] or [Date, null]
    • Time Picker: Single: { hours: number; minutes: number; seconds?: number } | Range: Array of the same object
    • Week Picker: Single: [Date, Date] | Range: [[Date, Date], [Date, Date]]
    • Month Picker: Single: { month: number; year: number } | Range: Array of the same object
    • Year Picker: Single: number | Range: [number, number]
    • Quarter Picker: Single: Date | Range: [Date, Date]

  7. Update CSS class names when migrating from v12

    In v12, all internal class names were renamed from using underscores (_) to dashes (-). If you have custom style overrides, you must update your selectors. Most class names maintain the same wording but use dashes.

    Specific renaming mappings:

    • dp__date_hover → dp--date-hoverable
    • dp__active_date → dp--active
    • dp__date_hover_start → dp--date-hoverable-start
    • dp__date_hover_end → dp--date-hoverable-end

    The following classes have been removed: dp__range_end, dp__range_start, dp--extended-fixed-start, and dp--extended-fixed-end.

    /* Old v12 style */
.dp__calendar_row {
  /* Custom overrides */
}

/* New style */
.dp--calendar-row {
  /* Custom overrides */
}

/* Old v12 style */
.dp__calendar_header_cell {
  /* Custom overrides */
}

/* New style */
.dp--calendar-header-cell {
  /* Custom overrides */
}

  8. Register VueDatePicker globally in a Vue 3 application

    To use the VueDatePicker component throughout your entire application, import the component and its CSS file in your main entry file and register it using app.component().
    import { createApp } from "vue";
import App from './App.vue';
import { VueDatePicker } from '@vuepic/vue-datepicker';
import '@vuepic/vue-datepicker/dist/main.css'

const app = createApp(App);
app.component('VueDatePicker', VueDatePicker);
app.mount('#app');

  9. Call VueDatePicker methods programmatically using refs

    To call internal VueDatePicker methods from external code, assign a ref to the component. In Vue 3 with <script setup>, use useTemplateRef with the InstanceType<typeof VueDatePicker> to get a type-safe reference to the component instance.
    <template>
  <VueDatePicker v-model="date" ref="datepicker" />
</template>

<script lang="ts" setup>
  import { VueDatePicker } from "@vuepic/vue-datepicker";
  import { ref, useTemplateRef } from 'vue';

  const date = ref();
  const dpRef = useTemplateRef<InstanceType<typeof VueDatePicker>>('datepicker');

  const yourCustomMethod = () => {
    dpRef.value?.closeMenu()
  }
</script>

  10. Automatically switch between range and single picker

    The model-auto prop allows the picker to switch between range and single modes automatically.

    Requirements:

    • The range prop must be provided.
    • range.partialRange must be set to true.
    • This is only compatible with standard date pickers; specific modes (like month/year pickers) are not supported.
    <template>
  <VueDatePicker v-model="date" model-auto range />
</template>

<script setup>
  import { VueDatePicker } from "@vuepic/vue-datepicker"
  import { ref } from 'vue';

  const date = ref();
</script>

  11. Migrate VueDatePicker from v11 to v12

    Migrating to the latest version of VueDatePicker requires vue >= v3.5. Several breaking changes have been introduced, including the removal of Compat mode and umd/iife bundles. The component must now be imported using a named import rather than a default import.
    import { VueDatePicker } from '@vuepic/vue-datepicker';

  12. Register VueDatePicker locally in a Vue component

    Import the VueDatePicker component and its required CSS file directly within the component where it will be used. This is compatible with <script setup>, the Composition API, and the Options API.
    <template>
  <VueDatePicker v-model="date"></VueDatePicker>
</template>

<script setup>
  import { ref } from 'vue';
  import { VueDatePicker } from '@vuepic/vue-datepicker';
  import '@vuepic/vue-datepicker/dist/main.css'

  const date = ref();
</script>