Skip to content
KahunaCart

Powered by Grav CMS + Helios Theme

The picker

A nightly product displays a date-range picker where guests choose arrival and departure dates. It appears automatically when the booking rule is set to Nightly stay; see Getting started.

This page covers the guest experience and the read-only availability calendar you can embed elsewhere.

Before you begin

  • A published rental product with an applicable schedule. If no dates appear, check The owner’s side.
  • The picker includes its own script and stylesheet; no theme changes are required.

Responsive calendar layout

The picker shows two months where space permits and one in narrow containers.

The picker measures its container. A narrow column or dialog can show one month even on a wide screen. It redraws when the container changes size and keeps the selected calendar position.

Set --kc-picker-max on the picker’s container to control its maximum width. Defaults are 58rem for the booking panel and 44rem for the read-only calendar. For a wider layout:

CSS
.my-property-page { --kc-picker-max: none; }

Use none to remove the width cap. Above 900px, the panel places the summary beside the calendar.

Use Earlier and Later to move one month at a time. When no dates are available, the panel displays Nothing is free in these months. Try looking further ahead.

Calendar date states

The calendar displays the same five date states as the admin:
Free Tinted, and pressable
Taken Struck through
Arrivals only A diagonal split marks an occupied previous night and an available arrival afternoon.
Departures only The opposite diagonal split marks an available departure morning and an unavailable night.
Blocked Shut, with the reason on it

The two halves are the whole point. A changeover day is genuinely half spoken for and half not, and on a property that is doing well it is what every Saturday in August looks like. A calendar that only knows free and busy has to give the whole date to one party, and that throws away a night a week. See A stay's rules.

Unavailable date explanations

Unavailable dates show reasons such as 3 nights minimum, Arrivals on Saturdays, Booked or That date has been and gone. The reason appears below the calendar on hover and in the date’s screen-reader label.

The picker applies stay rules during selection. Once arrival is selected, invalid departure dates are disabled, including dates that break length limits or overlap another booking.

A free night may still be invalid as an arrival date. Minimum stays, weekday rules or gap prevention can rule out the proposed stay. The calendar explains the relevant restriction.

Stay summary and pricing

The summary itemises rate bands, extra guests and cleaning. It also shows the total, payment due today, balance deadline, damage deposit and cancellation policy.

The summary uses the server quote saved with the hold and cart line. The browser does not calculate prices. Price it on the Rates tab and the CLI use the same pricing engine.

Hold dates and add to cart

Press Hold these dates to reserve the selected nights temporarily. A countdown shows when the hold expires. Change the dates releases the hold and returns to selection.

Use Add to cart to continue through checkout. The cart line retains the quoted price, dates and guest count.

When a hold expires, the panel shows Those dates are no longer held. Pick them again and reloads availability.

A stay with nothing to pay skips the basket. A property priced at nothing, or one set to be paid for on arrival, offers Book it instead: a name, an email, and the guest is booked in on the spot with a reference and an email on its way. No cart, no order, nothing to reconcile. See Taking payment.

Keyboard and screen reader support

The calendar supports these keyboard controls:

Key What it does
Arrow keys A day at a time, up and down by a week
Page Up / Page Down A month at a time
Home / End The first and last day of the month
Enter or Space Chooses the date
Escape Starts again

Only the active date is in the tab order. Use arrow keys to move between dates.

A live region announces the selected range, night count and price as they change, or the reason a selection is unavailable. Each date also has a spoken label with its state and any restriction.

Reschedule a stay

From the booking management page, Move it reopens the picker. Availability excludes the guest’s existing reservation so it does not block their own date selection.

The hint above the calendar is honest about the limit: the new dates have to come to the same amount, so a week in August will not move to a week at Christmas, and the guest is asked to ring you for that. See A stay's rules.

Embed an availability calendar

Use [kahunacart-availability] to embed a read-only availability calendar on a listing page, sidebar or other content page.

TXT
[kahunacart-availability product="beach-house" months="2" /]
[kahunacart-availability product="beach-house" /]

and in a template:

TWIG
{{ kahunacart_availability('beach-house') }}
{{ kahunacart_availability('beach-house', { months: 3 }) }}
Attribute What it is
product The property's product slug. Required — anything else answers an empty string rather than an error
service Accepted as a spelling of product, for anybody who thinks of it as the service
months 1 to 12, anything outside that clamped. Two by default

months sets the maximum number of months to display. The calendar fits as many as its container allows and redraws when that width changes. A setting of three shows three months where space permits.

The Twig function accepts the product slug followed by an options map that overrides its defaults.

The embedded calendar uses the same availability endpoint as the picker. Rendering errors return an empty string, so an invalid slug does not break the page. Shortcode Core is required for the shortcode; see Shortcodes.