postMessage events

React to widget interactions and control the calendar theme from the parent page.

Outbound events (from widgets)

RentalBeam widgets emit window.parent.postMessage events to the parent page. You can listen for these on any page where a widget is embedded to react to user interactions without modifying the widget code. Booking events come from the booking widget (Pro); the widget.resized event comes from iframe embeds of both widgets and from booking widget script embeds.

Listening for events

window.addEventListener('message', function (event) {
  // Always check the source before acting on messages.
  if (event.data.source !== 'rentalbeam') return;

  switch (event.data.event) {
    case 'booking.dates_selected':
      console.log('Dates selected:', event.data.data);
      break;

    case 'booking.dates_cleared':
      console.log('Dates cleared');
      break;

    case 'booking.unit_selected':
      console.log('Unit selected:', event.data.data);
      break;
  }
});

booking.dates_selected

Emitted by the booking widget each time a valid check-in and check-out date pair is selected. Fires on every change, not just on form submit.

// event.data shape when booking.dates_selected fires
{
  source: 'rentalbeam',
  event: 'booking.dates_selected',
  data: {
    checkIn: '2025-08-01',   // YYYY-MM-DD local date string
    checkOut: '2025-08-08',  // YYYY-MM-DD local date string
    nights: 7,
    widgetId: 'a1b2c3d4-...'
  }
}

booking.dates_cleared

Emitted by the booking widget when both dates are fully cleared. Useful for resetting dependent UI state.

// event.data shape when booking.dates_cleared fires
{
  source: 'rentalbeam',
  event: 'booking.dates_cleared',
  data: {
    widgetId: 'a1b2c3d4-...'
  }
}

booking.unit_selected

Emitted by the booking widget in a collection whenever the booked rental changes - when the guest picks a rental after choosing dates (the default dates-first flow) or up front (the Cards and Dropdown pickers). Useful for per-rental analytics or reflecting the chosen rental elsewhere on your page. Single-rental widgets do not emit it.

// event.data shape when booking.unit_selected fires
{
  source: 'rentalbeam',
  event: 'booking.unit_selected',
  data: {
    unitId: 'a1b2c3d4-...',        // UUID of the booked rental
    unitLabel: 'Cabin A',          // the rental's display name
    collectionId: 'c1d2e3f4-...',  // UUID of the collection (this event only fires inside one)
    price: 540                      // total for the selected range, or null when a rental is picked before dates
  }
}

widget.resized

Emitted by boththe availability calendar and the booking widget whenever the widget’s rendered height changes - on first load, calendar navigation, or as the booking form expands. It fires from iframe embeds of both widgets, and from booking widget script embeds too. A booking widget script embed renders the form through a frame it sizes automatically, so you never need to handle the event there. A copied <iframe>snippet for either widget is deliberately fixed-height with no relay on the host page - listen for this event yourself (see below) if you want a plain iframe embed to reflow with its content. The availability calendar’s script embed renders directly in the page and grows with it naturally, so it does not emit this event.

// event.data shape when widget.resized fires
{
  source: 'rentalbeam',
  event: 'widget.resized',
  data: {
    height: 612   // widget content height in pixels
  }
}

To size a custom iframe to its content:

// Size a RentalBeam iframe to its content. Needed for a plain <iframe> embed -
// those are fixed-height with no relay. Script embeds manage their own iframe
// and resize automatically, so you never need this listener for them.
window.addEventListener('message', function (event) {
  if (event.source !== iframe.contentWindow) return;
  var d = event.data;
  if (d && d.source === 'rentalbeam' && d.event === 'widget.resized'
      && typeof d.data.height === 'number') {
    iframe.style.height = d.data.height + 'px';
  }
});

Event envelope fields

Every outbound event from a RentalBeam widget shares the same top-level envelope:

Reserved internal events

On pages using the booking widget script embed you may also see widget.overlay, widget.prefill, and widget.open_launch messages. These coordinate the embed script with the booking form and are not part of the public contract - their names and payloads may change at any time, so do not build on them. The events documented above are the stable surface.

Example: Wix Velo integration

A common use case is syncing booking widget date selections into Wix native date picker components so they can drive other Wix automations or form submissions.

// Wix Velo - paste in the page's JavaScript panel
$w.onReady(function () {
  window.addEventListener('message', function (event) {
    if (event.data.source !== 'rentalbeam') return;

    if (event.data.event === 'booking.dates_selected') {
      var d = event.data.data;
      $w('#startDatePicker').value = new Date(d.checkIn);
      $w('#endDatePicker').value   = new Date(d.checkOut);
    }
  });
});

Inbound event (to the calendar widget)

The availability calendar widget accepts one inbound postMessage from the parent page to control its theme. This is separate from the outbound events emitted by the booking widget above.

rentalbeam-theme-change

Send this from your page to the calendar iframe to switch between light and dark mode at runtime.

// Send from the parent page to the calendar iframe
calendarIframe.contentWindow.postMessage(
  { type: 'rentalbeam-theme-change', theme: 'dark' },
  'https://rentalbeam.com'
);