Vue Cal

Common errors

• Failed to resolve module specifier "vue-cal" (or similar 'module not found' error)

  cause The `vue-cal` package is not correctly installed, or the import path is incorrect, or bundler configuration issue.
  fix Ensure `vue-cal` is installed (`npm install vue-cal` or `yarn add vue-cal`). Verify the import statement `import VueCal from 'vue-cal'` is correct and that your bundler supports ESM.

• The calendar component renders with zero height or is not visible.

  cause Vue Cal needs a defined height from its parent container or directly on the component to render properly.
  fix Apply a `height` style to the `<vue-cal>` component or its immediate parent element (e.g., `<div style="height: 600px;"><VueCal /></div>` or `<VueCal style="height: 600px;" />`).

• Uncaught SyntaxError: Cannot use import statement outside a module (or similar CommonJS errors)

  cause Attempting to use `require('vue-cal')` in a modern Vue 3 project, which primarily uses ES Modules.
  fix Switch to ES module imports: `import VueCal from 'vue-cal';` and ensure your project's build setup (e.g., `package.json` type, bundler config) supports ES Modules.

• Type '...' is not assignable to type 'VueCalEvent'. Property '...' is missing in type '...'.

  cause When using TypeScript, event objects or `VueCal` props are not correctly typed according to `vue-cal`'s declarations.
  fix Refer to the `vue-cal` documentation or its TypeScript declaration files (`.d.ts`) for the correct interface for event objects and component props. Ensure all required properties are present and correctly typed.

Warnings

• breaking Vue Cal v4.x is no longer actively maintained. While stable, new features and ongoing support have shifted to Vue Cal v5. Users planning long-term projects or requiring the latest features should consider migrating to v5, which is a complete rewrite and introduces breaking changes.
  Fix: For new projects, consider `npm i vue-cal@next` and refer to the v5 documentation. For existing v4 projects, plan for a migration path by reviewing the v5 breaking changes if upgrades are desired.
• gotcha Vue Cal requires its parent container or the component itself to have a defined height. If no height is set, the calendar will not render correctly (e.g., appear with zero height).
  Fix: Ensure the `<vue-cal>` component or its direct parent has a CSS `height` property defined (e.g., `height: 600px;` or `height: 100%;` if the parent has a height).
• deprecated Vue Cal's legacy branch for Vue 2 support (`npm i vue-cal@legacy`) has reached End-Of-Life and will not receive further updates or support.
  Fix: For Vue 2 projects, remain on the `legacy` branch but be aware of no future updates. For new projects or upgrades, use Vue 3 with `vue-cal` v4.x or v5.x.
• gotcha The calendar's default CSS is minimal and intentionally not styled with `!important` flags, encouraging users to easily override styles. Direct modification of the component's internal styles can lead to unexpected behavior during updates.
  Fix: Customize appearance by adding CSS classes to events or the `<vue-cal>` component and targeting those classes in your stylesheet. Refer to the documentation for available CSS variables and thematic classes (e.g., `vuecal--blue-theme`).
• gotcha When handling events, especially during drag-and-drop operations, the `originalEvent` property in emitted event objects (e.g., `@event-drop`) might return date values as strings instead of `Date` objects, requiring manual parsing.
  Fix: Always explicitly parse date strings (e.g., `new Date(event.originalEvent.start)`) if you expect `Date` objects from event payloads, particularly for properties like `start` or `end`.

Install

• npm install vue-cal npm
• yarn add vue-cal yarn
• pnpm add vue-cal pnpm

Imports

• VueCal
  wrong:

  const VueCal = require('vue-cal')

  correct:

  import VueCal from 'vue-cal'

  Vue Cal is a Vue component designed for ESM imports. CommonJS `require` syntax is not supported for component imports in modern Vue 3 setups.
• styles
  wrong:

  import 'vue-cal/dist/vuecal.scss'

  correct:

  import 'vue-cal/dist/vuecal.css'

  The compiled CSS is required for the calendar's basic styling. Raw SCSS is not exposed for direct import.
• Localized Messages

  import 'vue-cal/dist/i18n/fr.js'

  For internationalization, import the desired language file. This example imports French (`fr.js`). Other languages are available in `dist/i18n`.

Quickstart

This quickstart demonstrates a basic Vue Cal setup in a Vue 3 Composition API component, including event data, a custom theme, and essential styling for proper display.

<template>
  <div class="calendar-container">
    <VueCal 
      class="vuecal--blue-theme"
      :selected-date="new Date()"
      :time-step="30"
      :disable-views="['years', 'year']"
      :events="events"
      @ready="onCalendarReady"
      @event-create="onEventCreate"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import VueCal from 'vue-cal';
import 'vue-cal/dist/vuecal.css';

const events = ref([
  {
    start: new Date(new Date().setHours(10, 0, 0, 0)).toISOString(),
    end: new Date(new Date().setHours(11, 30, 0, 0)).toISOString(),
    title: 'Meeting with John',
    content: 'Discuss project roadmap.',
    class: 'leisure'
  },
  {
    start: new Date(new Date().setHours(14, 0, 0, 0)).toISOString(),
    end: new Date(new Date().setHours(15, 0, 0, 0)).toISOString(),
    title: 'Team Sync',
    content: 'Weekly team catch-up.',
    class: 'work'
  }
]);

function onCalendarReady() {
  console.log('Vue Cal is ready!');
}

function onEventCreate(event: any) {
  console.log('Event created:', event);
  // In a real app, you'd typically add the event to your `events` array or backend.
}
</script>

<style>
.calendar-container {
  height: 600px; /* Crucial: Vue Cal needs a defined height */
  max-width: 900px;
  margin: auto;
}
.vuecal__event.leisure {
  background-color: #a3c4f3;
  border: 1px solid #75a7f0;
  color: #fff;
}
.vuecal__event.work {
  background-color: #90ee90;
  border: 1px solid #6cdd6c;
  color: #fff;
}
</style>