Vue Datepicker UI

2.3.0 · active · verified Sun Apr 19

Vue Datepicker UI is an open-source, lightweight datepicker component designed for seamless integration into Vue.js applications. It currently supports both Vue 2 (versions 2.x, with 2.3.0 being the latest minor release) and Vue 3 (versions 3.x, with 3.1.1 being the latest minor release, accessible via the `@vue3` npm tag). The library maintains a moderate release cadence, providing minor feature enhancements and bug fixes, as seen with recent updates like 2.3.0 and 3.1.1 which added a `reset` event and `showPickerInital` property respectively. A key differentiator is its modularity; style files are optional, allowing developers to completely customize the component's appearance or integrate it into existing design systems without conflicts. Furthermore, it boasts a smaller bundle size since version 2.0.0, contributing to improved application performance. The component provides essential date selection functionalities, including single and multi-picker modes, with features like a clear date button for enhanced user experience.

Common errors

```
Failed to resolve component: Datepicker (or VueDatepicker)
```
cause The component was imported but not correctly registered globally or locally in your Vue application.

fix Ensure the component is registered in your `components` option (for Options API) or imported and used in `<script setup>` (for Composition API in Vue 3, if using `@vuepic/vue-datepicker`). Example: `components: { Datepicker }`.
```
[Vue warn]: Component provided is not a function or object.
```
cause You are likely trying to use the Vue 2 version of `vue-datepicker-ui` with a Vue 3 application, or vice-versa, causing incompatibility.

fix Verify your installed `vue-datepicker-ui` package version matches your Vue.js runtime version. For Vue 2, use `vue-datepicker-ui@^2`. For Vue 3, use `vue-datepicker-ui@vue3` or consider `npm install @vuepic/vue-datepicker` for dedicated Vue 3 support.
```
Datepicker component appears unstyled or with incorrect layout.
```
cause The default CSS file was not imported, or conflicting styles are overriding it.

fix Add `import 'vue-datepicker-ui/lib/vuedatepickerui.css';` to your main JavaScript/TypeScript entry point or the component where the Datepicker is used. Ensure there are no higher-priority conflicting styles.

Warnings

breaking The `vue-datepicker-ui` package has distinct major versions for Vue 2 and Vue 3. Version 2.x is for Vue 2, while version 3.x (published under the `@vue3` tag) is for Vue 3. Using the incorrect version with your Vue runtime will lead to runtime errors.
Fix: For Vue 2 projects, install `npm install vue-datepicker-ui@^2`. For Vue 3 projects, install `npm install vue-datepicker-ui@vue3` or consider `@vuepic/vue-datepicker` which is a dedicated Vue 3 solution.
gotcha The default styles (`vuedatepickerui.css`) are optional. If you do not import them, the component will be unstyled. If you import them, you can customize them using CSS variables.
Fix: Ensure you `import 'vue-datepicker-ui/lib/vuedatepickerui.css';` in your main entry file or component if you want the default appearance. For custom styling, refer to the documentation on overriding CSS variables.
gotcha An issue with `v-model` not correctly binding in certain scenarios was fixed in version 2.2.0. Older versions might exhibit unexpected behavior with two-way data binding.
Fix: Upgrade to `vue-datepicker-ui@2.2.0` or newer to ensure stable `v-model` functionality.

Install

npm install vue-datepicker-ui npm
yarn add vue-datepicker-ui yarn
pnpm add vue-datepicker-ui pnpm

Imports

Datepicker
wrong:
```
const Datepicker = require('vue-datepicker-ui');
```
correct:
```
import Datepicker from 'vue-datepicker-ui';
```
This package is primarily ESM. For Vue 2, install `vue-datepicker-ui` (e.g., v2.3.0). For Vue 3, install `vue-datepicker-ui@vue3` (e.g., v3.1.1).
CSS Styles
```
import 'vue-datepicker-ui/lib/vuedatepickerui.css';
```
Import the default styles. These styles are optional and can be overridden or omitted for full custom styling.
Vue 3 Import (via @vuepic/vue-datepicker)
```
import { VueDatePicker } from '@vuepic/vue-datepicker';
import '@vuepic/vue-datepicker/dist/main.css';
```
While `vue-datepicker-ui` has a `@vue3` tag, the `@vuepic/vue-datepicker` package is a separate, more actively developed Vue 3 datepicker with full TypeScript support and different import paths and component names. Developers might choose this for new Vue 3 projects.

Quickstart

This Vue 2.x example demonstrates importing, registering, and using the `Datepicker` component for single date and date range selection with `v-model` and a clear button. It also includes the necessary CSS import.

<template>
  <div id="app">
    <h1>Select a Date</h1>
    <Datepicker v-model="selectedDate" :clear-button="true" date-format="DD.MM.YYYY"></Datepicker>
    <p>Selected Date: {{ selectedDate ? new Date(selectedDate).toLocaleDateString() : 'None' }}</p>

    <h2>Date Range Selection</h2>
    <Datepicker v-model="dateRange" range></Datepicker>
    <p>Range: {{ dateRange && dateRange.from && dateRange.to ? `${new Date(dateRange.from).toLocaleDateString()} - ${new Date(dateRange.to).toLocaleDateString()}` : 'None' }}</p>
  </div>
</template>

<script>
import Datepicker from 'vue-datepicker-ui';
import 'vue-datepicker-ui/lib/vuedatepickerui.css';

export default {
  name: 'App',
  components: {
    Datepicker
  },
  data() {
    return {
      selectedDate: null,
      dateRange: { from: null, to: null }
    };
  },
  mounted() {
    // Example: Set initial date to today
    this.selectedDate = new Date();
  }
};
</script>

<style>
/* Optional: Add some basic styling or overrides */
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
</style>

view raw JSON →