Vue Dropdown Datepicker

A simple and customizable dropdown datepicker vue component. Works with Vue 2.7+ and Vue 3 from the same package.

Check Examples

Requirements

• Vue 2.7.0 or later, or Vue 3.0.0 or later.
• Projects still on Vue 2.6 or below (Vue 2.7 is the last 2.x release) should stay on [email protected], which remains published on npm and is unaffected by this release.

Installation

Package manager

Using npm

npm i vue-dropdown-datepicker

Using yarn

yarn add vue-dropdown-datepicker

Using CDN

Pick the build matching your Vue major version:

<!-- Vue 3 -->
<script src="https://unpkg.com/vue-dropdown-datepicker@2/dist/v3/dropdown-datepicker.iife.js"></script>

<!-- Vue 2.7 -->
<script src="https://unpkg.com/vue-dropdown-datepicker@2/dist/v2/dropdown-datepicker.iife.js"></script>

jsDelivr works the same way, substituting unpkg.com for cdn.jsdelivr.net/npm.

Usage

ES module bundlers (Vite, webpack, etc.)

The package resolves to the right build automatically for import. If your bundler/toolchain needs one Vue major explicitly, use the /v2 or /v3 subpath import instead of the bare package name.

// Vue 3
import { createApp } from 'vue';
import DropdownDatepicker from 'vue-dropdown-datepicker';

createApp({
  components: { DropdownDatepicker },
}).mount('#app');

// Vue 2.7
import Vue from 'vue';
import DropdownDatepicker from 'vue-dropdown-datepicker';

new Vue({
  el: '#app',
  components: { DropdownDatepicker },
});

Plugin install (registers <DropdownDatepicker> globally)

// Vue 3
import { createApp } from 'vue';
import DropdownDatepicker from 'vue-dropdown-datepicker';

const app = createApp({ /* ... */ });
app.use(DropdownDatepicker);
app.mount('#app');

// Vue 2.7
import Vue from 'vue';
import DropdownDatepicker from 'vue-dropdown-datepicker';

Vue.use(DropdownDatepicker);

Browser (<script> tag, Vue 2.7 only)

Loading Vue 2.7 globally via <script> before this package's Vue-2 build auto-installs <DropdownDatepicker> as a global component (same as versions 1.x). Vue 3's CDN global does not support this auto-install pattern - call app.use(DropdownDatepicker) yourself instead, as shown above.

new Vue({
  el: '#app',
});

v-model

<DropdownDatepicker v-model="date"> works the same way regardless of which Vue major is installed - the component emits both the Vue 2 (value/input) and Vue 3 (modelValue/update:modelValue) v-model contracts together, so consumers never need to know which one applies:

<dropdown-datepicker v-model="date"></dropdown-datepicker>

Localized month names

Pass a locale prop (a BCP 47 tag, eg. 'en', 'fr', 'de-DE') to have month names come from the browser's built-in Intl.DateTimeFormat instead of the English monthLongValues/ monthShortValues defaults - no extra dependency needed:

<dropdown-datepicker locale="fr"></dropdown-datepicker>

If locale is unset, or set to an invalid/unsupported tag, the component falls back to monthLongValues/monthShortValues as before. Day/month/year field labels (dayLabel, monthLabel, yearLabel, etc.) are separate props and aren't affected by locale - set those yourself if you need them translated too.

Options

| Option | Type | Default |Comment | | ------------- | ------------- | ---------- |--------| | defaultDate | string | null | | | defaultDateFormat | string | 'yyyy-mm-dd' | also supports 'dd/mm/yyyy', 'mm/dd/yyyy', 'unix' | | displayFormat | string | 'ymd' | 'ymd', 'dmy', or 'mdy' | | submitFormat | string | 'yyyy-mm-dd' | | | submitId | string | null | | | minAge | int | null | | | maxAge | int | null | | | minYear | int | null | | | maxYear | int | null | | | minDate | string | null | yyyy-mm-dd | | maxDate | string | null | yyyy-mm-dd | | allowPast | boolean | true | | | allowFuture | boolean | true | | | wrapperClass | string | 'date-dropdowns'| | | dropdownClass | string | null | | | daySuffixes | boolean | true | | | monthSuffixes | boolean | true | | | monthFormat | string | 'long' | | | locale | string | null | BCP 47 locale tag, eg. 'en', 'fr', 'de-DE'. When set, month names come from Intl.DateTimeFormat for that locale, overriding monthLongValues/monthShortValues. Falls back to monthLongValues/monthShortValues if unset or if the locale tag is invalid. | | required | boolean | false | | | dayLabel | string | 'Day' | | | monthLabel | string | 'Month' | | | yearLabel | string | 'Year' | | | sortYear | string | 'desc' | | | monthLongValues | array | ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']| | | monthShortValues | array | ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] | | | initialDayMonthYearValues| array | ['Day', 'Month', 'Year'] | | | daySuffixValues | array | ['st', 'nd', 'rd', 'th'] | |

Events

v-model / onChange

See the v-model section above for two-way binding. Alternatively, pass an onChange callback prop to receive the selected day/month/year directly:

<dropdown-datepicker v-bind:on-change="yourFunctionName"></dropdown-datepicker>

onDayChange

Call on any change of day dropdown

<dropdown-datepicker v-bind:on-day-change="yourFunctionName"></dropdown-datepicker>

onMonthChange

Call on any change of month dropdown

<dropdown-datepicker v-bind:on-month-change="yourFunctionName"></dropdown-datepicker>

onYearChange

Call on any change of year dropdown

<dropdown-datepicker v-bind:on-year-change="yourFunctionName"></dropdown-datepicker>

Contributing

Feel free to submit any fixes or propose any additional functionality via pull request or issue, making sure any changes take place in /src.

Run npm install, then:

• npm run build builds both the Vue 2.7 (dist/v2) and Vue 3 (dist/v3) targets in one command (it swaps in the Vue 2.7 toolchain, builds, then restores the Vue 3 toolchain afterward - see CLAUDE.md for why the Vue 2.7 toolchain can't be a normal devDependency).
• npm run test:v3 / npm run test:v2 run the test suite against each Vue major (test:v2 requires npm run setup:v2-toolchain first).
• npm run lint runs ESLint.

License

ISC