Usage

The examples below are ordered from simplest to most advanced. Each one introduces new features on top of the previous examples.

1 Minimal calendar

The simplest possible calendar. Events are defined directly in the YAML front matter under a named key (here minimal), and then rendered with the toastui shortcode referencing that key. The default view is week view.

Every event needs at least three fields: title, start, and end. date time must be specified in this format: YYYY-MM-DDTHH:MM:SS. The calendar defaults to today’s date rather than the event date. And this would look like a blank calendar even though the event is present in the calendar. Therefore, it is recommended to always provide a date field.

---
toastui:
  minimal:
    date: "2026-04-01"
    events:
      - title: "Big event"
        start: "2026-04-01T10:00:00"
        end: "2026-04-01T16:00:00"
---

{{< toastui minimal >}}

2 Month view

The user can change to different views such as month, day, or week views, but you can initially set the default view using the defaultView field in the calendar configuration. Here is a single event in month view. The user can be disallowed from changing the view if navigation is set to false.

---
toastui:
  month-view:
    defaultView: month
    date: "2026-04-01"
    events:
      - title: "Big event"
        start: "2026-04-01T10:00:00"
        end: "2026-04-01T16:00:00"
---

{{< toastui month-view >}}

3 Day view

Switch to a day view to see a detailed hour-by-hour timeline. This is useful when you want to focus on a single day’s agenda. Set defaultView: day and set date to the target day.

toastui:
  day-view:
    defaultView: day
    date: "2026-04-15"
    events:
      - title: "Standup"
        start: "2026-04-15T09:00:00"
        end: "2026-04-15T09:30:00"
      - title: "Deep Work"
        start: "2026-04-15T10:00:00"
        end: "2026-04-15T12:00:00"
      - title: "Lunch"
        start: "2026-04-15T12:00:00"
        end: "2026-04-15T13:00:00"
      - title: "Code Review"
        start: "2026-04-15T14:00:00"
        end: "2026-04-15T15:30:00"

{{< toastui day-view >}}

4 Categories and Duration

In week and day views, we can see different categories of events, namely Milestone, Task and All Day events. This is defined using the category field in the event data. We have updated the YAML metadata to include different event categories. We can also limit the displayed daily durations for each day by specifying hourStart and hourEnd.

toastui:
  categories-and-duration:
    defaultView: day
    date: "2026-04-15"
    week:
      hourStart: 9
      hourEnd: 17
    events:
      - title: "Standup"
        category: time
        start: "2026-04-15T09:00:00"
        end: "2026-04-15T09:30:00"
      - title: "Deep Work"
        category: task
        start: "2026-04-15T10:00:00"
        end: "2026-04-15T12:00:00"
      - title: "Lunch"
        start: "2026-04-15T12:00:00"
        end: "2026-04-15T13:00:00"
      - title: "Code Review"
        category: "milestone"
        start: "2026-04-15T14:00:00"
        end: "2026-04-15T15:30:00"
      - title: "Picnic"
        category: "allday"
        start: "2026-04-16"
        end: "2026-04-16"
        isAllday: true

{{< toastui categories-and-duration >}}

The display of categories Task and Milestone can be controlled using taskView by setting it as true, false, milestone or task.

toastui:
  categories-and-duration:
    week:
      taskView: false

toastui:
  categories-and-duration:
    week:
      taskView: 'milestone'

5 Automatic hour range

Instead of picking hourStart/hourEnd by hand, set autoHourRange: true to fit the time grid to the exact min/max timed extent of the events shown, with no padding. Here the events run 09:00–15:30, so the grid fits to exactly that range.

toastui:
  auto-hour-range:
    defaultView: day
    date: "2026-04-15"
    autoHourRange: true
    events:
      - title: "Standup"
        start: "2026-04-15T09:00:00"
        end: "2026-04-15T09:30:00"
      - title: "Deep Work"
        start: "2026-04-15T10:00:00"
        end: "2026-04-15T12:00:00"
      - title: "Code Review"
        start: "2026-04-15T14:00:00"
        end: "2026-04-15T15:30:00"

{{< toastui auto-hour-range >}}

Setting week.hourStart or week.hourEnd explicitly alongside autoHourRange: true keeps that side fixed and only auto-fits the other.

6 All-day and multi-day events

Events can span entire days or stretch across multiple days. Set category: allday and isAllday: true for all-day events. They are rendered in a banner at the top of the calendar. Regular timed events appear alongside them in the time grid.

events:
  - title: "Sprint Planning"
    category: allday
    start: "2026-04-14"
    end: "2026-04-14"
    isAllday: true
  - title: "Conference"
    category: allday
    start: "2026-04-16"
    end: "2026-04-18"
    isAllday: true
    backgroundColor: "#ff6b6b"
  - title: "Workshop"
    category: time
    start: "2026-04-15T09:00:00"
    end: "2026-04-15T12:00:00"

{{< toastui allday >}}

7 Calendars

This example introduces calendars — named colour groups that let you visually distinguish event categories. Each event references a calendar via calendarId.

toastui:
  calendars:
    defaultView: week
    date: "2026-04-09"
    events:
      - title: "Morning Run"
        calendarId: cal1
        category: time
        start: "2026-04-09T06:00:00"
        end: "2026-04-09T07:00:00"
      - title: "Team Standup"
        calendarId: cal2
        category: time
        start: "2026-04-09T09:00:00"
        end: "2026-04-09T09:30:00"
      - title: "Design Review"
        calendarId: cal2
        category: time
        start: "2026-04-10T14:00:00"
        end: "2026-04-10T15:30:00"
    calendars:
      - id: cal1
        name: Personal
        backgroundColor: "#03bd9e"
      - id: cal2
        name: Work
        backgroundColor: "#00a9ff"

{{< toastui calendars >}}

8 Event and popup details

Use eventDetailItems to add optional details inside timed events. Enable useDetailPopup: true and use popupDetailItems to select optional popup rows independently. Both accept any field in the event data, including custom columns from delimited files. Known TOAST UI fields such as location and attendees use their native icons; custom fields render as field: value. Both options default to no optional details and only show selected fields that exist in the event data. Popup title and date are always visible. Set timeFormat to "12h" or "24h" to use one format for rendered timed event labels, the time-grid axis, the current-time indicator, and this popup. The default is "24h". The separate event form popup time picker remains in TOAST UI’s built-in 24-hour format.

toastui:

  popup:
    defaultView: week
    date: "2026-04-14"
    useDetailPopup: true
    eventDetailItems:
      - location
      - attendees
      - project
    popupDetailItems:
      - location
      - attendees
      - project
    timeFormat: "24h"
    calendars:
      - id: cal1
        name: Work
        color: "#ffffff"
        backgroundColor: "#00a9ff"
        dragBackgroundColor: "#00a9ff"
        borderColor: "#00a9ff"
    events:
      - title: "Design Review"
        calendarId: cal1
        category: time
        start: "2026-04-14T09:00:00"
        end: "2026-04-14T11:30:00"
        location: "Room A"
        attendees: "Alice"
        project: "Apollo"
      - title: "Sprint Retro"
        calendarId: cal1
        category: time
        start: "2026-04-15T14:00:00"
        end: "2026-04-15T15:00:00"
        location: "Main Hall"
        attendees: "Bob"
        project: "Gemini"

{{< toastui popup >}}

9 Events from a TSV file

Instead of listing events in YAML, point file to a tab-separated file and set file-sep to "\t". Here is the format of the TSV file:

id  calendarId  title   category    start   end isAllday    location    backgroundColor
101 cal1    TSV Demo Meeting    time    2026-04-14T09:00:00 2026-04-14T10:00:00 false   Room North  #03bd9e
102 cal2    TSV Sprint Review   time    2026-04-15T13:00:00 2026-04-15T14:00:00 false   Studio B    #00a9ff
103 cal1    TSV Planning Day    allday  2026-04-16  2026-04-16  true    HQ  #03bd9e

The file must have a header row with at least the columns title, start, and end. Optional columns like calendarId, category, location, and backgroundColor are picked up automatically.

toastui:
  tsv-events:
    defaultView: month
    date: "2026-04-01"
    height: 620px
    file: data/events.tsv
    file-sep: "\t"

{{< toastui tsv-events >}}

10 Events from a CSV file

Comma-delimited files work the same way — just change file-sep to ",". Here is a preview of the CSV file format:

id,calendarId,title,category,start,end,isAllday,location,backgroundColor
201,cal1,CSV Demo Meeting,time,2026-04-17T09:30:00,2026-04-17T10:15:00,false,Room East,#03bd9e
202,cal2,CSV Design Sync,time,2026-04-18T14:00:00,2026-04-18T15:00:00,false,Online,#00a9ff
203,cal2,CSV Release Day,allday,2026-04-19,2026-04-19,true,Remote,#00a9ff

This example also uses the week view so you can see the timed events on the grid.

toastui:
  csv-events:
    defaultView: week
    date: "2026-04-17"
    file: data/events.csv
    file-sep: ","

{{< toastui csv-events >}}

11 Fully inline shortcode

You can skip YAML metadata entirely and pass all options directly in the shortcode. This style is handy for quick one-off calendars or prototypes. Nested structures like calendars or week options can also be passed inline as a JSON string (see the timezone example under Inline parameter tests), but this gets unwieldy fast — YAML metadata is more readable for anything beyond a couple of flat options.

{{< toastui file="data/events.tsv" file-sep="\t" defaultView="day" date="2026-04-15" >}}

12 Inline override of metadata

You can combine YAML metadata with inline arguments. The metadata key provides the base configuration, and any inline arguments override individual values. Here the custom-height config is reused but switched to month view with a different date and height.

{{< toastui custom-height defaultView="month" date="2026-04-01" height="500px" >}}

13 Full-featured schedule

This example puts it all together: events loaded from a CSV file, custom calendar colours for different event types, detail popups, timezone configuration, a workweek-only week view with custom hour range, and an enlarged time grid. This pattern is well suited for multi-day workshops and conference programmes. height and timegridHeight are manually set to remove scroll bar.

Note on timezone: the CSV’s start/end columns use plain wall-clock timestamps (2026-10-05T09:00:00, no UTC offset) because timezone.zones[0].timezoneName is set to Europe/Stockholm — every viewer sees these events at the stated Stockholm time, regardless of their own device’s timezone, with DST handled automatically. See Time Zones in the repo README for details.

toastui:
  schedule:
    defaultView: week
    file: "data/schedule.csv"
    file-sep: ","
    date: "2026-11-16"
    useDetailPopup: true
    height: 960px
    timegridHeight: 900px
    week:
      workweek: true
      taskView: false
      eventView: ['time']
      hourStart: 9
      hourEnd: 21
      showNowIndicator: true
    timezone:
      zones:
        - timezoneName: Europe/Stockholm
    eventDetailItems:
      - attendees
    popupDetailItems:
      - attendees
      - calendar
    calendars:
      - id: "session"
        name: "Session"
        backgroundColor: "#D6EAF8"
        borderColor: "#85C1E9"
      - id: "free"
        name: "Free"
        backgroundColor: "#FCF3CF"
        borderColor: "#F7DC6F"
      - id: "extra"
        name: "Extra"
        backgroundColor: "#E8DAEF"
        borderColor: "#BB8FCE"

{{< toastui schedule >}}

14 Limitations

• RevealJS is supported but known to be flaky
• For other formats, the shortcode emits no output
• Short duration events may not be displayed legibly depending on the max day duration
• The calendar may not display legibly on very small screens

---
toastui:
  limitations:
    date: "2026-04-01"
    events:
    - title: "30 min event"
      start: "2026-04-01T10:00:00"
      end: "2026-04-01T10:30:00"
    - title: "15 min event"
      start: "2026-04-01T11:00:00"
      end: "2026-04-01T11:15:00"
    - title: "10 min event"
      start: "2026-04-01T12:00:00"
      end: "2026-04-01T12:10:00"
    - title: "5 min event"
      start: "2026-04-01T13:00:00"
      end: "2026-04-01T13:05:00"
---

{{< toastui limitations >}}