Vue Simple Calendar

Common errors

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

  cause The `Calendar` component was not correctly imported and registered in your Vue application or a specific component's `components` option, preventing Vue from rendering it.
  fix Ensure you have `import { Calendar } from 'vue-simple-calendar'` in your script setup or `<script>` block, and if not using `<script setup>`, ensure `Calendar` is listed in your component's `components: { Calendar }` option or globally registered with `app.component('Calendar', Calendar)`.

• ReferenceError: require is not defined

  cause This error occurs when attempting to use the CommonJS `require()` syntax to import `vue-simple-calendar` within a modern Vue 3 project, which typically utilizes ES Modules (ESM).
  fix Update your module import statements to use the ES Module syntax: `import { Calendar } from 'vue-simple-calendar'`.

• TypeError: Invalid prop: type check failed for prop "items". Expected Array, got Object

  cause The `items` prop, which expects an array of calendar item objects, was provided with a JavaScript object instead.
  fix Ensure that the `items` prop is always bound to a JavaScript array, where each element conforms to the `ICalendarItem` interface or a compatible object structure.

Warnings

• breaking Version 6.0 introduced significant breaking changes, migrating the component to Vue 3 and Vite, and explicitly dropping support for Internet Explorer 11. Users on Vue 2 or those requiring IE11 compatibility must remain on `vue-simple-calendar@5`, which is no longer actively maintained.
  Fix: Upgrade your project to Vue 3 and ensure your target browser compatibility aligns with modern evergreen browsers. If Vue 2/IE11 support is critical, revert to `vue-simple-calendar@5` but be aware that it will not receive updates or bug fixes.
• gotcha The library developer notes difficulties in configuring Vite to both emit TypeScript declaration files (`.d.ts`) during the build and maintain Hot Module Replacement (HMR) for development. This could lead to an inconsistent TypeScript experience or missing type definitions in specific development environments.
  Fix: If encountering TypeScript declaration issues, check the project's GitHub issues for potential workarounds or consider generating declaration files separately if your build process allows. You might need to add manual type declarations for missing types.
• gotcha Vue Simple Calendar is primarily designed for desktop web applications. While it may function on mobile devices, its utility might be limited due to screen resolution constraints. Crucially, drag-and-drop features are exclusively supported on desktop browsers and do not function on touch devices.
  Fix: For mobile experiences, consider implementing alternative interaction patterns or disabling drag-and-drop functionality conditionally. Test thoroughly on target mobile devices to ensure a satisfactory user experience.

Install

• npm install vue-simple-calendar npm
• yarn add vue-simple-calendar yarn
• pnpm add vue-simple-calendar pnpm

Imports

• Calendar
  wrong:

  const Calendar = require('vue-simple-calendar')

  correct:

  import { Calendar } from 'vue-simple-calendar'

  The primary calendar component for Vue 3. It's often registered as `<Calendar>` in your application or component's `components` option.
• ICalendarItem
  wrong:

  import { ICalendarItem } from 'vue-simple-calendar'

  correct:

  import type { ICalendarItem } from 'vue-simple-calendar'

  Type definition for calendar items, which is essential for ensuring type safety and autocomplete in TypeScript projects. Always use `import type` for interfaces.
• CalendarView
  wrong:

  import CalendarView from 'vue-simple-calendar'

  correct:

  import { CalendarView } from 'vue-simple-calendar'

  An alternative named export for the main component. While `Calendar` is often preferred for usage brevity, `CalendarView` is also available and points to the same component definition.

Quickstart

Demonstrates how to install and integrate Vue Simple Calendar into a Vue 3 TypeScript component, displaying a basic calendar with sample events (including multi-day items) and handling date/item click events. It also includes basic styling imports and custom class usage.

<!-- src/App.vue -->
<template>
  <div id="app">
    <h1>My Event Calendar</h1>
    <div style="width: 80%; margin: 0 auto;">
      <Calendar
        :showDate="currentDate"
        :items="calendarItems"
        :startingDayOfWeek="1"
        @clickDate="onClickDate"
        @clickItem="onClickItem"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, reactive } from 'vue';
import { Calendar, type ICalendarItem } from 'vue-simple-calendar';
import 'vue-simple-calendar/dist/style.css';
import 'vue-simple-calendar/dist/css/default.css'; // Or your custom theme CSS

const currentDate = ref(new Date());

const calendarItems: ICalendarItem[] = reactive([
  { id: '1', startDate: new Date(2026, 3, 10), endDate: new Date(2026, 3, 12), title: 'Multi-day Event', class: 'custom-event-class' },
  { id: '2', startDate: new Date(2026, 3, 15, 9, 0), endDate: new Date(2026, 3, 15, 10, 30), title: 'Meeting (9:00 AM)' },
  { id: '3', startDate: new Date(2026, 3, 20), title: 'Project Deadline' },
  { id: '4', startDate: new Date(2026, 3, 25), endDate: new Date(2026, 4, 1), title: 'Week-long Project', class: 'long-project' }
]);

function onClickDate(date: Date) {
  console.log('Clicked date:', date.toLocaleDateString());
}

function onClickItem(item: ICalendarItem) {
  console.log('Clicked item:', item.title, 'on', item.startDate.toLocaleDateString());
}
</script>

<style>
/* Basic styling, replace with your custom theme */
#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;
}

/* Custom classes for calendar items */
.custom-event-class {
  background-color: #a7f3d0;
  color: #065f46;
  border-radius: 4px;
  padding: 2px 4px;
}

.long-project {
  background-color: #bfdbfe;
  color: #1e40af;
  border-radius: 4px;
  padding: 2px 4px;
  opacity: 0.9;
}
</style>