Docs
Calendar
Configuration

Calendar configuration

This page describes a few of the config-options available. Some options, however, require more in-depth understanding and are therefore documented in separate pages.

Options in the calendar config

import { createCalendar, viewMonthGrid } from '@schedule-x/calendar'
import '@schedule-x/theme-default/dist/index.css'
 
const config = {
  // ... views, events and other options
 
  /**
   * Set the language. List of supported languages: https://schedule-x.dev/docs/calendar/supported-languages
   * For support of further languages, please open a PR, adding your translations under the folder:
   * packages/translations/src/locales/xx-XX
   *
   * Defaults to 'en-US'
   * */
  locale: 'zh-CN',
 
  /**
   * Set which day is to be considered the starting day of the week. 0 = Sunday, 1 = Monday, (...other days) 6 = Saturday
   * Defaults to 1 (Monday)
   * */
  firstDayOfWeek: 0,
 
  /**
   * The preferred view to display when the calendar is first rendered.
   * all views that you import have a "name" property, which helps you identify them.
   * Defaults to the first view in the "views" array
   * */
  defaultView: viewMonthGrid.name,
 
  /**
   * The default date to display when the calendar is first rendered. Only accepts YYYY-MM-DD format.
   * Defaults to the current date
   * */
  selectedDate: '2023-12-24',
 
  /**
   * Render the calendar in dark mode.
   * Defaults to false
   * */
  isDark: true,
 
  /**
   * Decides which hours should be displayed in the week and day grids. Defaults to midnight - midnight (a full day)
   * Can also be set to a "hybrid" day, such as { start: '06:00', end: '03:00' }, meaning each day starts at 6am but
   * extends into the next day until 3am.
   * */
  dayBoundaries: {
    start: '06:00',
    end: '18:00',
  },
 
  /**
   * The minimum and maximum date that can be displayed
   * */
  minDate: '2024-01-01',
  maxDate: '2024-12-31',
 
  weekOptions: {
    /**
     * The total height in px of the week grid (week- and day views)
     * */
    gridHeight: 2500,
 
    /**
     * The number of days to display in week view
     */
    nDays: 5,
 
    /**
     * The width in percentage of the event element in the week grid
     * Defaults to 100, but can be used to leave a small margin to the right of the event
     */
    eventWidth: 95,
 
    /**
     * Intl.DateTimeFormatOptions used to format the hour labels on the time axis
     * Default: { hour: 'numeric' }
     */
    timeAxisFormatOptions: { hour: '2-digit', minute: '2-digit' },
  },
 
  monthGridOptions: {
    /**
     * Number of events to display in a day cell before the "+ N events" button is shown
     * */
    nEventsPerDay: 8,
  },
 
  /**
   * Toggle automatic view change when the calendar is resized below a certain width breakpoint.
   * Defaults to true
   * */
  isResponsive: false,
 
  /**
   * Skip validating events when initializing the calendar. This can help you gain a bit of performance if you are loading a lot of events,
   * and you are sure that the events are valid.
   * */
  skipValidation: true,
 
  /**
   * Callbacks for events that occur in the calendar
   * */
  callbacks: {
    /**
     * Is called when:
     * 1. Selecting a date in the date picker
     * 2. Selecting a new view
     * */
    onRangeUpdate(range) {
      console.log('new calendar range start date', range.start)
      console.log('new calendar range end date', range.end)
    },
 
    /**
     * Is called when an event is updated through drag and drop
     * */
    onEventUpdate(updatedEvent) {
      console.log('onEventUpdate', updatedEvent)
    },
 
    /**
    * Is called before an event is updated by drag & drop or resizing.
    * If you return false, the update will be aborted,
    * and the event will be reset to its original position.
    * If you return true, the event will be updated.
    * */
    onBeforeEventUpdate(oldEvent, newEvent, $app) {
      // run your validation or side effects
      return false
    },
 
    /**
     * Is called when an event is clicked
     * */
    onEventClick(calendarEvent) {
      console.log('onEventClick', calendarEvent)
    },
 
    /**
     * Is called when an event is double clicked
     * */
    onDoubleClickEvent(calendarEvent) {
      console.log('onDoubleClickEvent', calendarEvent)
    },
 
    /**
     * Is called when clicking a date in the month grid
     * */
    onClickDate(date) {
      console.log('onClickDate', date) // e.g. 2024-01-01
    },
 
    /**
     * Is called when clicking somewhere in the time grid of a week or day view
     * */
    onClickDateTime(dateTime) {
      console.log('onClickDateTime', dateTime) // e.g. 2024-01-01 12:37
    },
 
    /**
     * Is called when selecting a day in the month agenda
     * */
    onClickAgendaDate(date) {
      console.log('onClickAgendaDate', date) // e.g. 2024-01-01
    },
 
    /**
     * Is called when double clicking a day in the month agenda
     * */
    onDoubleClickAgendaDate(date) {
      console.log('onDoubleClickAgendaDate', date) // e.g. 2024-01-01
    },
 
    /**
     * Is called when double clicking a date in the month grid
     * */
    onDoubleClickDate(date) {
      console.log('onClickDate', date) // e.g. 2024-01-01
    },
 
    /**
     * Is called when double clicking somewhere in the time grid of a week or day view
     * */
    onDoubleClickDateTime(dateTime) {
      console.log('onDoubleClickDateTime', dateTime) // e.g. 2024-01-01 12:37
    },
 
    /**
     * Is called when clicking the "+ N events" button of a month grid-day
     * */
    onClickPlusEvents(date) {
      console.log('onClickPlusEvents', date) // e.g. 2024-01-01
    },
 
    /**
     * Is called when the selected date is updated
     * */
    onSelectedDateUpdate(date) {
      console.log('onSelectedDateUpdate', date)
    },
 
    /**
     * Runs on resizing the calendar, to decide if the calendar should be small or not.
     * This in turn affects what views are rendered.
     * */
    isCalendarSmall($app) {
      return $app.elements.calendarWrapper?.clientWidth! < 500
    },
 
    /**
     * Runs before the calendar is rendered
     * */
    beforeRender($app) {
      const range = $app.calendarState.range.value
      fetchYourEventsFor(range.start, range.end)
    },
 
    /**
     * Runs after the calendar is rendered
     * */
    onRender($app) {
      console.log('onRender', $app)
    },
  },
}
 
const calendar = createCalendar(config)
 
calendar.render(document.getElementById('calendar'))