Copy page

Booking widget

Events and the store

The widget tells the page what happens through DOM events, and the page's own code can drive the booking through the root's store.

Events

Every event goes out from the <mellow-booking> root, or from a <mellow-search> that stands alone. Each one bubbles and is composed, so it also leaves a shadow root. Listen on the root, or on document:

Code
document.addEventListener("mellow-booked", (event) => {
  const { id, reference } = event.detail;
  window.dataLayer?.push({ event: "booking", reference });
});

Event	detail	Meaning
mellow-ready	{ rental }	The rental, its locations and its car types are in.
mellow-step	{ from, to, path }	The booking moves to another step. path is the address of the new step. Cancelable: a cancelled move does not happen. See Pages and paths for a site with its own router.
mellow-search	{ pickup, return, pickupAt, returnAt, driverAge, coupon, mref }	The customer sends a search. Cancelable: a cancelled search changes nothing.
mellow-choose	{ carTypeId }	The customer chose a car type.
mellow-details	{ carTypeId }	The customer opened a car type's details. carTypeId is the car type's id.
mellow-quote	{ currency, days, payNowMinor, totalMinor }	A new price for the order. The detail is the whole quote of the API, with these fields and more.
mellow-before-book	Record<string, unknown>	The customer pressed Pay. The detail is the hold's request. Cancelable: a cancelled Pay holds no car, for the site's own last checks.
mellow-booked	{ id, reference }	The processor's paid webhook made the booking, or a pay-on-arrival hold booked with no payment. With a test key, reference is 0.
mellow-paid	{ id, reference, amount, currency }	Straight after mellow-booked, with the amount paid in minor units and its currency.
mellow-error	{ code, message }	The API refused something, such as none_free. message is in the customer's language.
mellow-currency	{ currency }	The customer picked a currency to see prices in. Shown only: the charge stays in the rental's.
mellow-term	{ refundable, confirmationBp }	The customer picked a payment term. refundable and confirmationBp name it, and a new quote follows.

A cancelable event is cancelled with event.preventDefault().

In Vue, write @mellow-booked="…". In React 19, write onmellow-booked={…}: React takes a prop that starts with on as a listener on a custom element. The Next.js recipe shows it.

The store

The root has the store of its booking. A site that needs more than the events reads it and sends actions to it. The store is ready once storeReady settles:

Code
const booking = document.querySelector("mellow-booking");
const store = await booking.storeReady;

store.getState(); // the search, the car type, the products, the quote, the step and the rest
const stop = store.subscribe((state) => console.log(state.step)); // gives an unsubscribe
store.setSearch({ pickupAt: "2027-06-01T10:00", returnAt: "2027-06-04T10:00" });
store.choose(carTypeId);
store.setProduct(productId, 1); // 0 takes it off
store.goTo("driver");

Action	What it does
getState()	The state now.
subscribe(fn)	Calls fn with the new state after each change. Gives an unsubscribe.
setSearch(search)	Changes the search: pickup, return, pickupAt, returnAt, driverAge, coupon, mref.
choose(carTypeId)	Chooses a car type.
setProduct(productId, n)	Takes a product n times. 0 takes it off. A level or a package with cover takes the place of the one picked.
decline(productId, on)	Refuses a cover that is on every booking, or takes it back. Only a cover that may be refused.
setCustomer(customer)	Changes the customer's details: firstName, lastName, email, phone and the rest.
setCurrency(code)	Shows prices in another currency. The charge stays in the rental's.
missing(step)	What a step still needs, the current step by default. Empty when it is complete.
goTo(step), next(), back()	Moves to a step, the next one or the one before. goTo and next give false and stay when a step before is not complete.
locate()	Reads the address again, after the site's own router moved.
pay()	Does what the Pay button does.

Locations, car types and products go by their id from the API. The API reference describes each one.