The canonical stay URL
View .mdEvery Kismet site carries the stay a guest is shopping for in the URL under ONE
set of key names, so a search bar, a results page, and a property page agree
with each other across reloads, shared links, and the move to a property page.
The stay-query contract makes this a MUST: keys come from the
StayUrlParam enum (or a registered site param), and reads and writes go
through the SDK helpers only.
One stay store; the URL is its mirror
Section titled “One stay store; the URL is its mirror”A page holds ONE stay (checkIn, checkOut, guests). Every surface reads
it and writes it: the search bar or island, the result cards and their dated
prices, the quick-view sheet, the booking rail, the map, and the similar row.
No surface keeps its own committed dates, and no surface writes the URL
directly. The URL mirrors the store for share, reload, and back/forward. A
lone check-in (no check-out yet) stays in its calendar until the stay is
complete.
In the SDK the store is the stay-query channel: read with useStayQuery or
subscribeStayQuery, write with the useStayQuery updater or
writeStayQueryToLocation. These helpers are the only code that writes the
stay into the URL. The search-island recipe scenario checks it on rendered
pages (conformance/search-island-stay-store-sync).
The canonical keys
Section titled “The canonical keys”StayUrlParam is the single enum. Never spell these keys as string literals —
compare the enum member, or derive the key lists from it.
| Key | Meaning | Default | Written |
|---|---|---|---|
checkIn, checkOut |
ISO days; both or neither, checkOut > checkIn |
omitted | data |
guests |
integer 1–16 | 2 (omitted) | data |
beds, sleeps |
minimums; 0 means any | 0 (omitted) | data |
minPrice, maxPrice |
whole currency units | omitted | data |
currency |
ISO-4217-style code; only with a price bound | USD |
data |
sort |
recommended · price-asc · price-desc · name-asc · bedrooms · sleeps |
recommended |
data |
pets, type, group, tags, prioritize |
optional filters | omitted | data |
sheet |
slug of the open quick view | omitted | UI-only |
layout |
grid · map |
grid |
UI-only |
Two write modes, one shared list: data keys change results, so useStayQuery
writes them with router.replace({ scroll: false }). UI-only keys (sheet,
layout) are written shallow with history.replaceState and never trigger a
server re-read of results. STAY_DATA_PARAM_KEYS, STAY_UI_PARAM_KEYS, and
ALL_STAY_PARAM_KEYS all derive from the enum.
Read and write through the helpers
Section titled “Read and write through the helpers”import { parseStayQuery, stayQueryToSearchParams } from '@kismet-tech/sdk';
const stayQuery = parseStayQuery(searchParams); // invalid values fall back silentlyconst href = `/properties?${stayQueryToSearchParams(stayQuery).toString()}`;A param at its default is omitted; garbage is dropped, never thrown. Use
countStayNights(stayQuery) and describeActiveStaySettings(stayQuery) for
nights and the active-settings line.
The one hook (React and Next)
Section titled “The one hook (React and Next)”const [stayQuery, updateStayQuery] = useStayQuery({ router, isKnownSheetSlug });
updateStayQuery({ checkIn: '2026-10-12', checkOut: '2026-10-15' }); // router.replace, scroll: falseupdateStayQuery({ sheet: 'fern-ridge-cabin' }); // shallow write, no re-readupdateStayQuery({ sheet: undefined }); // close: removedSheet rules: written shallow, removed on close, read after hydration, an
unknown slug resolves to closed (isKnownSheetSlug), and preserved when data
keys change. A Next App Router adapter — createNextStayQueryController from
@kismet-tech/sdk/next — takes useRouter() / usePathname() /
useSearchParams() outputs as-is and follows the same two write modes.
Site-specific params (L4)
Section titled “Site-specific params (L4)”A site-specific param must be namespaced x-<site>-<name> and registered;
anything else is an invented key. Registration goes into the same registry the
parser, serializer, build gate, and kismet check read. Unprefixed keys and
built-in collisions are refused.
export const acmeView = defineStayParam({ key: 'x-acme-view', mode: 'ui', parse: (raw) => (raw === 'list' || raw === 'grid' ? raw : undefined), default: 'grid',});Compliance is required, not advised
Section titled “Compliance is required, not advised”Two gates back the contract’s MUSTs and MUST NOTs:
content/stay-params(runtime,npx kismet check) — fails on any rendered link carrying an invented stay key (?minBedrooms=2,?check_in=…,?price_min=…).recipes/stay-query-source(static,npx kismet recipes check --app-dir ., the starters’check:recipes) — fails when a file that declares thestay-querycontract touchessearchParams/URLSearchParams/router.push|replaceoutside the SDK helpers, or uses a non-canonical, unregistered key.
Where to go next: What is a contract for the requirement levels, and Recipes and implementation tests for declaring implementations.
Use the shared calendar
Section titled “Use the shared calendar”Use StayDatesField from @kismet-tech/fixtures for search dates. It wraps
StayDatesCalendar, the same Elements calendar as the search island. Import
@kismet-tech/fixtures/styles.css in the root layout. SDK-first sites use it too.
For a property, pass its typed calendar to retain nightly rates and stay rules,
or use BookableProductStayPicker for the full selection surface.
Read committed dates with useStayQuery, write completed ranges with its updater,
and keep only a half-picked check-in local. Clear both dates; do not restore
fallback dates. Results routes must refresh server-owned dated cards and summaries
after island edits. The SDK and Elements share the date-change event protocol.
kismet recipes check --app-dir . rejects native booking inputs under
recipes/stay-calendar-source. It permits unrelated date fields and hidden stay
fields. It cannot prove a copied calendar equivalent. Test desktop and phone:
select in each control, confirm synchronization, reload a future dated link,
open the selected month, clear, and check keyboard dismissal.
kismet init --update adds this guidance to the generated agent instructions.