behnoo-calendar

@dopedev/vue-calendar

A multi-calendar Vue 3 component supporting Gregorian, Jalaali (Persian), and Islamic calendar systems with full RTL support.

Features

• Three calendar systems: Gregorian, Jalaali (Persian), Islamic (Umm al-Qura)
• Three view modes: monthly, weekly, daily
• RTL layout support
• Fully customizable header via slot
• Event display with color, duration, and full-day support
• Dark mode via CSS custom properties
• TypeScript support

Installation

npm install @dopedev/vue-calendar
# or
pnpm add @dopedev/vue-calendar

Setup

Import the stylesheet once in your app entry point:

import "@dopedev/vue-calendar/style.css";

Nuxt:

// nuxt.config.ts
export default defineNuxtConfig({
  css: ["@dopedev/vue-calendar/style.css"],
});

Basic Usage

<script setup lang="ts">
import { ref } from "vue";
import { VueCalendar } from "@dopedev/vue-calendar";
import type { CalendarEvent } from "@dopedev/vue-calendar";

const events = ref<CalendarEvent[]>([
  {
    id: 1,
    title: "Team Meeting",
    date: new Date(),
    time: "10:00",
    duration: 60,
    color: "#3b82f6",
  },
]);
</script>

<template>
  <div style="height: 600px">
    <VueCalendar :events="events" />
  </div>
</template>

The component fills its container — give the parent a fixed height.

Props

v-model

mode supports two-way binding:

<VueCalendar v-model:mode="mode" />

Events

Header Slot

Replace the default header entirely with the #header slot. All navigation and mode control is exposed through slot props:

<VueCalendar :events="events" v-model:mode="mode">
  <template #header="{ mode, range, next, prev, setMode }">
    <div class="flex items-center gap-2 p-3 border-b">
      <button @click="prev">←</button>
      <button @click="next">→</button>
      <span>{{ range.start.toLocaleDateString() }}</span>
      <div class="ml-auto flex gap-1">
        <button
          v-for="m in ['monthly', 'weekly', 'daily'] as const"
          :key="m"
          @click="setMode(m)"
          :class="mode === m ? 'font-bold' : ''"
        >
          {{ m }}
        </button>
      </div>
    </div>
  </template>
</VueCalendar>

Slot props

Calendar Systems

Gregorian (English)

<VueCalendar calendar-type="gregory" locale="en-US" :start-of-week="1" />

Jalaali / Persian (RTL)

Wrap the component in dir="rtl" to get correct RTL layout. Note that next and prev in the header slot remain semantically correct — swap their visual arrow directions instead.

<div dir="rtl">
  <VueCalendar
    calendar-type="persian"
    locale="fa-IR"
    :start-of-week="6"
  />
</div>

Islamic / Umm al-Qura (RTL)

<div dir="rtl">
  <VueCalendar
    calendar-type="islamic-uma"
    locale="ar-SA"
    :start-of-week="0"
  />
</div>

Customizing Event Display

You can override how events are rendered in the time‑grid (weekly/daily) and in the mobile monthly list.

• Desktop time‑grid: use the #event slot.
• Mobile event list: use the #event-mobile slot.

<VueCalendar :events="events">
  <!-- Custom desktop event -->
  <template #event="{ event }">
    <div :style="{ background: event.color || '#3b82f6', padding: '4px', borderRadius: '6px' }">
      {{ event.title }}
    </div>
  </template>

  <!-- Custom mobile list event -->
  <template #event-mobile="{ event }">
    <div class="flex items-center gap-2">
      <span class="font-bold">{{ event.title }}</span>
      <span class="text-sm text-gray-500">{{ event.time }}</span>
    </div>
  </template>
</VueCalendar>

CalendarEvent

interface CalendarEvent {
  id: number | string;
  date: Date | string; // date of the event
  time: string; // 'HH:mm' format
  title: string;
  duration?: number; // minutes (used in weekly/daily view)
  color?: string; // hex or CSS value; defaults to --cal-primary
  isFullDay?: boolean;
  raw?: any; // attach your original API payload here
}

Theming

The calendar exposes a set of CSS custom properties for colours. You can override them on :root for the light theme and inside a .dark selector for the dark theme.

Today badge gradient
You can change the gradient used for the “today” circle:

Example customisation:

:root {
  --color-surface: #ffffff;
  --color-primary: #ff6b6b;
  --cal-today-bg-light: radial-gradient(circle at 70% 0%, #4a00e0, #8e2de2);
}

.dark {
  --color-surface: #111827;
  --color-primary: #ff8787;
  --cal-today-bg-dark: radial-gradient(circle at 70% 0%, #ffd700, #ff8c00);
}

Exposed Methods

When using a template ref, the component exposes:

const cal = ref<InstanceType<typeof VueCalendar>>();

cal.value?.goNext(); // navigate forward
cal.value?.goPrev(); // navigate backward
cal.value?.setMode("weekly"); // change view mode
cal.value?.currentRange; // { start: Date, end: Date }

TypeScript

All public types are exported from the package root:

import type {
  CalendarEvent,
  CalendarMode,
  CalendarType,
  CalendarDay,
  CalendarDateRange,
  CalendarTimeRange,
} from "@dopedev/vue-calendar";

Development

pnpm install
pnpm dev          # dev sandbox at http://localhost:5173
pnpm type-check   # TypeScript check
pnpm build:lib    # build the distributable package

Run the Nuxt example

pnpm build:lib

cd examples/nuxt-example
pnpm install
pnpm dev          # http://localhost:3000

Publishing

npm login         # log in with the @dopedev org account
npm publish       # prepublishOnly runs build:lib automatically

License

MIT