Vue 3 Datepicker

Common errors

• [Vue warn]: Failed to resolve component: Datepicker

  cause The Datepicker component was not correctly imported or registered in your Vue application.
  fix Ensure you have `import Datepicker from 'vuejs3-datepicker';` in your script and that it's correctly registered in your component's `components` option or globally with `app.component('Datepicker', Datepicker)`.

• TypeError: Cannot read properties of null (reading 'toLocaleDateString')

  cause Attempting to call methods on a `Date` object when the bound variable is `null` or `undefined` (e.g., when the date is cleared).
  fix Always check if your date variable is not `null` or `undefined` before attempting to call `Date` object methods on it, e.g., `selectedDate.value ? selectedDate.value.toLocaleDateString() : 'No date'`.

• TypeError: date.getFullYear is not a function

  cause The `value` or `v-model` prop was passed a value that is not a JavaScript `Date` object, but a string or other type that the component could not parse into a valid Date.
  fix Ensure that the `value` or `v-model` prop is always bound to a valid JavaScript `Date` object or `null` if no date is selected. If passing a string, ensure it's in a format the component can natively parse, or convert it to a `Date` object before passing.

• Styles are not applied, datepicker looks unstyled.

  cause The component's default CSS styles were not imported into the project.
  fix Add `import 'vuejs3-datepicker/dist/vuejs3-datepicker.css';` to your main Vue entry file (e.g., `main.ts` or `main.js`) or within a component's style block if using a build system that supports it.

Warnings

• breaking This library is exclusively compatible with Vue 3. Attempting to use it in a Vue 2 project will result in runtime errors due to fundamental API differences.
  Fix: Ensure your project is built with Vue 3. If you need Vue 2 compatibility, use a different datepicker library.
• gotcha The `value` prop and `v-model` both control the date. While `v-model` internally uses `modelValue` and `update:modelValue` in Vue 3, this component also exposes a `value` prop. It's recommended to primarily use `v-model` for consistency and idiomatic Vue 3 data binding.
  Fix: Prefer using `v-model="yourDateVariable"` for two-way data binding. If you need one-way binding, you can pass `:value="yourDateVariable"` and listen to the `@selected` event for updates.
• gotcha If you utilize the `clear-button` or `calendar-button` props and specify an `icon` (e.g., `fa fa-times`), you must ensure that the corresponding icon library (like Font Awesome) is separately installed and imported into your project. The component does not bundle these icons.
  Fix: Install and configure the desired icon library (e.g., `npm install @fortawesome/fontawesome-free` and import its CSS) in your Vue application.
• gotcha The v1.1.3 release included a bug fix for 'update hook name for directives'. While marked as a fix, this indicates an internal adjustment related to Vue 3's directive lifecycle hooks. Developers with highly customized directives interacting with this component might need to verify behavior, although it's unlikely to affect standard usage.
  Fix: No direct fix required for most users, but be aware of potential subtle behavioral changes if you extensively customize Vue directives that might interact with the datepicker's internal rendering.

Install

• npm install vuejs3-datepicker npm
• yarn add vuejs3-datepicker yarn
• pnpm add vuejs3-datepicker pnpm

Imports

• Datepicker
  wrong:

  const Datepicker = require('vuejs3-datepicker');

  correct:

  import Datepicker from 'vuejs3-datepicker';

  The component is a default export. Primarily designed for ESM environments with Vue 3. Using CommonJS `require` might lead to bundler issues or require specific configuration.
• Datepicker (Global Registration)
  wrong:

  Vue.component('Datepicker', Datepicker);

  correct:

  import Datepicker from 'vuejs3-datepicker';
  
  app.component('Datepicker', Datepicker);

  For global registration in Vue 3, use `app.component` (after creating your Vue app instance). Direct use of `Vue.component` is for Vue 2 applications.
• CSS Styles

  import 'vuejs3-datepicker/dist/vuejs3-datepicker.css';

  Ensure to import the default CSS styles for the datepicker to render correctly. You can override styles with `calendar-class` or `input-class` props.

Quickstart

This quickstart demonstrates a basic Vue 3 setup using the `vuejs3-datepicker` component. It shows importing the component, using `v-model` for two-way binding, custom date formatting, enabling the clear button, setting Monday as the first day of the week, and handling `selected` and `closed` events. It also includes a programmatic way to clear the date.

<template>
  <div id="app">
    <h2>Select a Date</h2>
    <datepicker v-model="selectedDate" :format="'dd MMMM yyyy'"
                :clear-button="true" :monday-first="true"
                @selected="handleDateSelection" @closed="handleCalendarClose">
    </datepicker>
    <p>Selected Date: {{ selectedDate ? selectedDate.toLocaleDateString() : 'None' }}</p>
    <button @click="clearDate">Clear Date</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import Datepicker from 'vuejs3-datepicker';

const selectedDate = ref<Date | null>(new Date());

const handleDateSelection = (date: Date) => {
  console.log('Date selected:', date);
  // v-model already updates selectedDate, but you can add other logic here.
};

const handleCalendarClose = () => {
  console.log('Datepicker closed.');
};

const clearDate = () => {
  selectedDate.value = null;
};
</script>

<style>
/* Basic styling for demonstration, replace with your project's styles */
#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>