DOCSEARCHbyAlgolia
Submit Docs

EventCalendar Documentation

repository·master·Indexed 24 days ago

https://github.com/vkurko/calendar

A lightweight, zero-dependency, drag-and-drop JavaScript event calendar featuring resource and timeline views. Built with CSS Grid for high performance, it provides a native Svelte 5 component, a JavaScript module via @event-calendar/core, and a standalone CDN bundle. Version 5.11.1 supports dynamic event loading via eventSources, interaction plugins for dragging and resizing, and extensive customization of toolbar buttons, day cells, and event styling.

Tokens
14.5K
Snippets
22
Records
91
Agent score
80%

What's inside EventCalendar

  1. Define Event object properties

    master

    An Event object stores all information for a calendar event. Key properties include:

    • id: Unique identifier.
    • resourceIds: Array of associated resource IDs.
    • allDay: Boolean for all-day slotting.
    • start / end: JavaScript Date objects.
    • title: The event's display content.
    • display: Rendering type ('auto' or 'background').
    • backgroundColor / textColor: Visual overrides.
    • classNames: Array of CSS classes.
    • styles: Array of inline CSS strings.
    • extendedProps: Plain object for miscellaneous custom data.

  2. Control event ordering in resourceTimeline views

    master

    The eventOrderStrict option (boolean, default false) determines how resourceTimeline views handle event placement.

    • Default (false): Prioritizes compactness. Events are placed in the topmost free slot, which may allow an event to move above an earlier-ordered event if space is available.
    • Strict (true): Maintains vertical order. An event will never be placed above another event that precedes it in eventOrder, even if free space exists above it. This is useful for ensuring parent events always stay above child events.

  3. Format event title content

    master

    The title property of an event (the content displayed on the event) can be provided in three formats:

    1. A plain string: 'some text'
    2. An HTML string object: {html: '<p>some HTML</p>'}
    3. An array of DOM nodes: {domNodes: [node1, node2, ...]}

  4. Manage time zones and event shifting

    master

    The timeZone option sets the time zone used to display dates and times. Accepted values:

    • 'local': Uses the browser's local time zone (Default).
    • 'UTC': Uses UTC (zero offset).
    • A UTC offset string: e.g., '+05:30' or '-06:00'.

    Behavior:

    • Event dates with explicit offsets (e.g., '2028-06-01T10:00:00+02:00') are shifted to the calendar's timezone.
    • Event dates without timezone info (e.g., '2028-06-01T10:00:00') are treated as floating and displayed as-is, but interpreted in the calendar's timezone.
    • Changing timeZone at runtime automatically shifts loaded events and the current date, and re-fetches events from eventSources.
    let ec = new EventCalendar(document.getElementById('ec'), {
    timeZone: '+02:00',
    events: [
        {
            start: '2028-06-01T10:00:00',        // floating — displayed as 10:00
            end:   '2028-06-01T12:00:00',
            title: 'Meeting'
        },
        {
            start: '2028-06-01T10:00:00+00:00',  // UTC — displayed as 12:00 in +02:00
            end:   '2028-06-01T12:00:00+00:00',
            title: 'Call'
        }
    ]
});

  5. Configure Resource objects and nesting

    master

    Resources allow you to associate events with specific entities (e.g., rooms, staff) and display them separately in resource views.

    Resource Properties

    • id: Unique string identifier (coerced from integer or string). Used to link events via their resourceIds field.
    • title: Text displayed for the resource.
    • eventBackgroundColor: Default background color for events in this resource.
    • eventTextColor: Default text color for events in this resource.
    • expanded: Boolean flag indicating if a resource with children is expanded or collapsed.
    • extendedProps: A plain object for miscellaneous custom properties.
    • children: An array of nested Resource objects.

    Nested Resources

    resourceTimeline views support hierarchical resources. You can define parent-child relationships using the children field. Parents can be collapsed or expanded via UI buttons.

    resources: [
  {
    id: 1,
    title: 'Resource A',
    children: [
      {
        id: 11,
        title: 'Resource A1'
      },
      {
        id: 12,
        title: 'Resource A2'
      }
    ]
  }
]

  6. Understand the Duration object

    master

    The Duration object is used by EventCalendar to represent periods of time (e.g., 30 minutes, 1 day and 6 hours).

    Properties

    • years: Number of years.
    • months: Number of months.
    • days: Number of days.
    • seconds: Total number of seconds. To derive hours or minutes, perform division on this value.
    • inWeeks: A boolean indicating if the duration represents a time period in weeks (set during parsing).

    Parsing Durations

    When providing values for options like duration, scrollTime, or slotDuration, EventCalendar accepts three formats:

    1. An object containing any of these keys: year, years, month, months, day, days, minute, minutes, second, seconds.
    2. A string in hh:mm:ss or hh:mm format (e.g., '05:00' for 5 hours).
    3. An integer representing the total number of seconds.

  7. Use EventCalendar via Standalone Bundle (CDN)

    master

    For quick integration without a build step, include the EventCalendar CSS and JS files via CDN in your HTML <head>. Use EventCalendar.create() to initialize and EventCalendar.destroy() to clean up.

    <!-- In <head> -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@event-calendar/build@5.11.1/dist/event-calendar.min.css">
<script src="https://cdn.jsdelivr.net/npm/@event-calendar/build@5.11.1/dist/event-calendar.min.js"></script>

<script>
let ec = EventCalendar.create(document.getElementById('ec'), {
    view: 'timeGridWeek',
    events: [
        // your list of events
    ]
});

// If you later need to destroy the calendar then use
EventCalendar.destroy(ec);
</script>

  8. Modify calendar options after initialization

    master

    You can update calendar settings dynamically after the instance has been created.

    • JavaScript Modules: Use the setOption(name, value) method on the calendar instance.
    • Svelte 5: Simply update the reactive options object passed to the <Calendar /> component.
    // JavaScript
ec.setOption('slotDuration', '01:00');
    <!-- Svelte 5 -->
<script>
    import {Calendar, TimeGrid} from '@event-calendar/core';

    let options = $state({
        view: 'timeGridWeek'
    });

    function updateOptions() {
        options.slotDuration = '01:00';
    }
</script>

<button onclick={updateOptions}>Change slot duration</button>
<Calendar plugins={[TimeGrid]} {options} />

  9. Access and use EventCalendar methods

    master

    Methods allow you to manipulate the calendar after initialization. These methods are accessible from the calendar instance. In Svelte, you access them via a component instance using bind:this.

    <script>
  import {Calendar, TimeGrid} from '@event-calendar/core';

  let ec = $state();
  let options = $state({
    view: 'timeGridWeek',
    eventSources: [{events: function() {
        console.log('fetching...');
        return [];
      }}]
  });

  function invokeMethod() {
    ec.refetchEvents();
  }
</script>

<button onclick={invokeMethod}>Refetch events</button>
<Calendar bind:this={ec} plugins={[TimeGrid]} {options} />

  10. Use EventCalendar as a JavaScript module

    master

    In a standard JavaScript environment, use createCalendar to initialize the calendar and destroyCalendar to clean it up. You must provide an HTML element, an array of plugins, and an options object. Ensure you import the core CSS.

    import {createCalendar, destroyCalendar, TimeGrid} from '@event-calendar/core';
// Import CSS if your build tool supports it
import '@event-calendar/core/index.css';

let ec = createCalendar(
    // HTML element the calendar will be mounted to
    document.getElementById('ec'),
    // Array of plugins
    [TimeGrid],
    // Options object
    {
        view: 'timeGridWeek',
        events: [
            // your list of events
        ]
    }
);

// If you later need to destroy the calendar then use
destroyCalendar(ec);

  11. Apply dark themes and customize colors

    master

    EventCalendar includes a built-in dark theme that can be activated via CSS classes on a parent element.

    Activating Dark Mode

    • Manual: Add the ec-dark class to a parent element (e.g., <body class="ec-dark">).
    • Automatic: Add the ec-auto-dark class to a parent element to follow the user's system prefers-color-scheme.

    Customizing Colors

    You can override the calendar's appearance by redefining CSS variables. For example, to change the background and text color:

    .ec {
  --ec-bg-color: #22272e;
  --ec-text-color: #adbac7;
}

    A full list of available CSS variables is located in packages/core/src/styles/theme.css.

  12. Use EventCalendar in Svelte 5

    master

    EventCalendar provides a native Svelte 5 component. Pass the required plugins via the plugins prop and the configuration via the options prop. The component handles graceful destruction automatically when the parent component is unmounted.

    <script>
    import {Calendar, TimeGrid} from '@event-calendar/core';

    let options = $state({
        view: 'timeGridWeek',
        events: [
            // your list of events
        ]
    });
</script>

<Calendar plugins={[TimeGrid]} {options} />