TOAST UI Calendar

TOAST UI Calendar is a full-featured JavaScript calendar with the following capabilities:

View Types

Supports multiple view modes including:

• Daily
• Weekly
• Monthly (with options for 2-week, 3-week, or 6-week views)
• 2 Weeks

Schedule Management

• Interactivity: Supports dragging and resizing schedules directly via mouse.
• Milestones: Efficient management of milestone and task schedules.
• Customization: Supports changing the start day of the week, customizing date/schedule UI (including grid cell headers and footers), and applying custom themes.
• Popups: Includes ready-to-use default popups for schedule creation and detail views.

Layout Features

• Supports narrow width for weekends.
• Supports customizing the UI for various view types.

Since user interactions (clicks, drags, etc.) cannot be controlled via direct method calls, TOAST UI Calendar uses an event-driven model. You can listen for predefined system events or register and trigger your own custom events using .on(), .once(), .off(), and .fire().

// Registering custom events and event handlers
calendar.on('myCustomEvent', (currentView) => {
  calendar.changeView(currentView === 'week' ? 'day' : 'month');
});

// Executing custom events
calendar.fire('myCustomEvent', calendar.getViewName());

The ThemeObject is the root configuration for the calendar's visual style. It is divided into three distinct parts based on the view type:

1. common: Applies styles to the entire application regardless of the view.
2. week: Applies styles specifically to the weekly and daily views.
3. month: Applies styles specifically to the monthly view.

All values provided in these objects must be valid CSS string values (e.g., 'red', '1px solid #000', 'rgba(0,0,0,0.5)').

interface ThemeObject {
  common: CommonTheme;
  week: WeekTheme;
  month: MonthTheme;
}

An EventObject is a pure JavaScript object used throughout the TOAST UI Calendar API. It is used for creating events, searching for specific events, and is provided as data in instance event handlers (e.g., when an event is clicked).

const calendar = new Calendar('#container');

// Using EventObject to create an event
calendar.createEvents([
  {
    id: '1',
    calendarId: 'cal1',
    title: 'timed event',
    body: 'TOAST UI Calendar',
    start: '2022-06-01T10:00:00',
    end: '2022-06-01T11:00:00',
    category: 'time',
    // ... other properties
  },
]);

// Receiving an EventObject from an event handler
calendar.on('clickEvent', ({ event }) => {
  console.log(event); // This is the EventObject
});

Install the TOAST UI Calendar for Vue 2 using npm. Note that this package requires Vue 2; Vue 3 is not supported.

npm install @toast-ui/vue-calendar # latest version
npm install @toast-ui/vue-calendar@<version> # specific version

To use the built-in event form and detail popups, set useFormPopup and/or useDetailPopup to true.

Important: When using useFormPopup, you must install and import the CSS files for tui-date-picker and tui-time-picker to ensure correct styling.

npm install tui-date-picker tui-time-picker

// Load css files of tui-date-picker and tui-time-picker to use the event form popup.
import 'tui-date-picker/dist/tui-date-picker.css';
import 'tui-time-picker/dist/tui-time-picker.css';

calendar.setOptions({
  useFormPopup: true,
  useDetailPopup: true,
});

TOAST UI Calendar provides default pop-ups for creating events (useFormPopup) and viewing event details (useDetailPopup). To use them, set these options to true.

Important: If using the event creation popup, you must also install and import the CSS for tui-date-picker and tui-time-picker to ensure correct styling.

npm install tui-date-picker tui-time-picker

import 'tui-date-picker/dist/tui-date-picker.css';
import 'tui-time-picker/dist/tui-time-picker.css';

calendar.setOptions({
  useFormPopup: true,
  useDetailPopup: true,
});

When upgrading the Vue wrapper (@toast-ui/vue-calendar) from v1 to v2, two primary breaking changes must be addressed:

1. Prop Renaming: The schedules prop has been renamed to events to better reflect the concept of calendar events.
2. Instance Access: Instead of using the invoke method to call calendar instance methods indirectly, you must now use the getInstance() method to retrieve the actual calendar instance and call methods directly on it.

In v2, the setTheme method has been improved to use nested objects instead of dot-notated string keys. Additionally, many specific styling properties (like font sizes and paddings for day names or more views) have been removed from the theme object and should now be applied via CSS.

Theme Object Structure Change:

// v1: Dot-notation strings
calendar.setTheme({
  'common.dayName.color': '#333',
});

// v2: Nested objects
calendar.setTheme({
  common: {
    dayName: {
      color: '#333',
    },
  },
});

CSS Fallbacks for removed theme properties: If you need to style elements that were previously available in the v1 theme (e.g., month.dayname.fontSize, week.dayname.height), use the following CSS file locations as a guide for targeting the correct elements.

You can customize the calendar behavior and appearance using an option object. Options can be provided in two ways:

1. During initialization: Pass an options object as the second argument to the Calendar constructor.
2. Dynamically: Use the setOptions method on an existing instance to update settings at runtime.

Common configuration tasks include setting the initial view, toggling read-only mode, or enabling built-in popups.

// Setting options when creating an instance
const calendar = new Calendar('#container', {
  defaultView: 'month',
  isReadOnly: true,
  // ...
});

// Changing options with the setOptions method
calendar.setOptions({
  defaultView: 'week',
  isReadOnly: false,
  // ...
});

The template feature allows for custom rendering of various calendar elements. You can define templates when initializing a new Calendar instance via the template option, or update them dynamically using the setOptions method.

Each template property is a function that must return either a preact VNode or a string. The parameters passed to these functions vary depending on the specific template being used (e.g., some receive an EventObject, while others receive no parameters).

const calendar = new Calendar('#container', {
  template: {
    milestone(event) {
      return `<span style="color: red;">${event.title}</span>`;
    },
  },
});

calendar.setOptions({
  template: {
    milestone(event) {
      return `<span style="color: blue;">${event.title}</span>`;
    },
  },
});