Integration

Integrate BookingJs, the timum booking widget, via script tag, ESM import, React component, or iframe – this page compares all the approaches.

Script Tag (CDN)

The simplest method of integration is using a script tag with our CDN. Ideal for static websites and quick prototypes.

<div id="bookingjs" style="margin: 32px"></div>
<script type="module">
  import * as timum from 'https://cdn.timum.de/bookingjs/1/booking.js';

  timum.init({ ref: 'booking-widget-demo-resource@timum' });
</script>

Working example on jsFiddle

With URL Parameter

<!-- URL: https://ihre-website.de?ref=ihre-ressourcen-referenz -->
<div id="bookingjs" style="margin: 32px"></div>
<script type="module">
  import * as timum from 'https://cdn.timum.de/bookingjs/1/booking.js';

  timum.init(); // Reference is read from the URL parameter
</script>

ESM Import

For modern JavaScript projects with build tools like Webpack, Vite, or Rollup, you can install the package as an npm dependency.

Installation

# With Yarn
yarn add @timum/booking

# With npm
npm install @timum/booking

Usage

import { init } from '@timum/booking';

// Make sure an element with id="bookingjs" exists
init({ ref: 'ihre-ressourcen-referenz' });

Example project on StackBlitz

React Component

For React applications, we offer a native component with full TypeScript support.

Installation

yarn add @timum/booking

Usage

import { TimumBooking } from '@timum/booking';

function BookingPage() {
  return (
    <TimumBooking
      appConfig={{
        ref: 'ihre-ressourcen-referenz',
        // additional options...
      }}
      muiTheme={{
        // MUI theme customizations (PRO)
      }}
    />
  );
}

With All Options

import { TimumBooking } from '@timum/booking';

function BookingPage() {
  return (
    <TimumBooking
      appConfig={{
        ref: 'ihre-ressourcen-referenz',
        prdRefs: 'produkt-referenz', // optional
        channelKey: 'RESOURCE_PUBLIC', // optional
        height: '600px',
        culture: 'de',
        callbacks: {
          createBookingSuccessful: ({ timeslot, data }) => {
            console.log('Termin gebucht:', timeslot);
          },
        },
      }}
      muiTheme={{
        palette: {
          primary: {
            main: '#337ab7',
          },
        },
        typography: {
          fontFamily: 'Inter, sans-serif',
        },
      }}
    />
  );
}

Multiple Instances on One Page

TimumBooking supports multiple booking widgets on the same page. Each instance automatically receives a unique iframe ID and manages its configuration in isolation – props, themes, and callbacks remain separate per instance, and everything is cleaned up properly on unmount.

import { TimumBooking } from '@timum/booking';

// Multiple widgets for different resources
<div>
  <TimumBooking appConfig={{ ref: 'resource-a@timum', height: '500px' }} />
  <TimumBooking appConfig={{ ref: 'resource-b@timum', height: '500px' }} />
</div>;

iframe (for Legacy Systems)

If your CMS does not allow script embedding: timum hosts a ready-made widget page for every reference at /widget/<referenz>. Use this URL directly as the iframe source – no hosting of your own required. Pass options such as language, appointment types, or channel as URL parameters.

<iframe
  src="https://www.timum.de/widget/ihre-ressourcen-referenz"
  width="100%"
  height="600"
  style="border: none;"
></iframe>

<!-- With options via URL parameter (e.g. language and appointment type) -->
<iframe
  src="https://www.timum.de/widget/ihre-ressourcen-referenz?culture=en&prdRefs=besichtigung"
  width="100%"
  height="600"
  style="border: none;"
></iframe>

View Variants

In addition to /widget/, there are further paths that render the same reference in other calendar views:

• /widget/<ref> – Default view
• /weekwidget/<ref> – Week calendar
• /weekstackwidget/<ref> – Compact week view
• /listwidget/<ref> – Pure list view
• /details-month-widget/<ref> – Month view with appointment details
• /details-week-widget/<ref> – Week view with appointment details

Custom Embed Page (for Event Communication)

The hosted widget page does not provide any callbacks. If you need events on the parent page, host a small page of your own instead, using the script tag snippet and postMessageTarget:

<!-- embed.html – your own page with the BookingJs snippet -->
<div id="bookingjs" style="margin: 32px"></div>
<script type="module">
  import * as timum from 'https://cdn.timum.de/bookingjs/1/booking.js';

  timum.init({
    ref: 'ihre-ressourcen-referenz',
    postMessageTarget: 'https://www.example.com' // Send events to the parent page
  });
</script>

<!-- Embed on your page -->
<iframe
  src="https://www.example.com/embed.html"
  width="100%"
  height="600"
  style="border: none;"
></iframe>

Comparison of Methods

Related Topics

• Entity Referencing
• Configuration
• Callbacks