postMessage events

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

Available onFreePlusPro

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 both widgets in iframe embeds.

Listening for events

JavaScript

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;
  }
});

Always guard with event.data.source !== 'rentalbeam'. Browser pages receive postMessage events from all iframes on the page - the source check prevents your handler from reacting to unrelated messages.

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.

JavaScript

// 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-...'
  }
}

Field	Type	Description
`checkIn`	`string`	YYYY-MM-DD local date string for the selected check-in date.
`checkOut`	`string`	YYYY-MM-DD local date string for the selected check-out date.
`nights`	`number`	Integer number of nights between check-in and check-out.
`widgetId`	`string`	UUID of the booking widget that emitted the event.

booking.dates_cleared

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

JavaScript

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

Field	Type	Description
`widgetId`	`string`	UUID of the booking widget that emitted the event.

booking.unit_selected

Emitted by the booking widget in a unit group whenever the booked unit changes - when the guest picks a unit (By date, Cards, or Dropdown) or the dates resolve to a unit (Auto). Useful for per-unit analytics or reflecting the chosen unit elsewhere on your page. Single-unit widgets do not emit it.

JavaScript

// event.data shape when booking.unit_selected fires
{
  source: 'rentalbeam',
  event: 'booking.unit_selected',
  data: {
    unitId: 'a1b2c3d4-...',   // UUID of the booked unit (calendar)
    unitLabel: 'Cabin A',     // the unit's display name
    groupId: 'g1h2i3j4-...',  // UUID of the unit group
    price: 540                 // current total for the range, or null if not yet priced
  }
}

Field	Type	Description
`unitId`	`string`	UUID of the booked unit's calendar.
`unitLabel`	`string`	Display name of the booked unit.
`groupId`	`string`	UUID of the unit group, or null.
`price`	`number`	The unit's current total for the selected range, or null if dates are not yet chosen / priced.

widget.resized

Emitted by boththe availability calendar and the booking widget (in iframe embeds) whenever the widget’s rendered height changes - on first load, calendar navigation, or as the booking form expands. The copied iframe embed snippet already includes a small relay script that listens for this and sizes the iframe to fit, so you only need to handle it yourself for custom iframe setups. The script (non-iframe) embed grows with the page naturally and does not emit this event.

JavaScript

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

Field	Type	Description
`height`	`number`	Widget content height in pixels (bound to a sane range). Set this as the iframe height.

To size a custom iframe to its content:

JavaScript

// Size a RentalBeam iframe to its content (only needed for custom iframe setups -
// the copied embed snippet already includes a relay that does this for you).
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:

Field	Type	Description
`source`	`string`	Always "rentalbeam". Use this to filter events in your listener.
`event`	`string`	Dot-namespaced event name. Format: widget.action (e.g. booking.dates_selected).
`data`	`object`	Event-specific payload. Shape varies by event - see individual tables above.

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.

JavaScript (Wix Velo)

// 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);
    }
  });
});

Wix Velo runs in a sandboxed environment. If the listener does not fire, verify that the iframe is added via the Wix Embed Code element and not a Wix iframe element - Velo has different message routing for each.

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.

JavaScript

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

Field	Value	Description
`type`	`string`	"rentalbeam-theme-change"
`theme`	`string`	"light" or "dark"