Skip to content

Host-controlled routing

The host application owns the URL. Coras pages emit navigation intents through onNavigate; you turn each intent into a URL, push it to your router, and reflect URL changes back into the mount with app.update().

The @coras-io/embed/url entry point provides framework-neutral helpers so you do not write URL parsing glue for each framework.

You need a working mount() call. See Get started if you have not mounted a page yet.

Import the URL helpers from the /url entry point:

import {
parseCorasUrl,
buildCorasUrl,
createCorasUrlState,
createCorasRouting,
isSameCorasUrlState,
} from "@coras-io/embed/url";

By default the helpers put locale and currency in the path and represent a details page as a bare id segment (for example /en-IE/EUR/abc123). The id is percent-encoded so characters like /, ?, and # round-trip. A details id that equals a reserved page segment (for example search) is not representable in this shape and is not supported:

const state = parseCorasUrl("/en-IE/EUR/search?search=museum");
// { page: "search", params: { search: "museum" }, locale: "en-IE", currency: "EUR" }
const url = buildCorasUrl({
page: "details",
params: { id: "abc123", date: "2026-06-01" },
locale: "en-IE",
currency: "EUR",
});
// "/en-IE/EUR/abc123?date=2026-06-01"

Locale uses BCP 47 tags (en-IE) and currency uses ISO 4217 codes (EUR). Aliases and casing are normalized during parsing. The shape is yours to choose: the Coras-run sites write a lower-case locale and keep the currency out of the URL when it is the locale’s default (/en-ie/abc123), which is the shape the snippets below use and the one we recommend for a new site. See Customize the URL strategy; an existing site keeps its shape unless it opts in.

If your router validates the locale and currency path params, make that validation fall back rather than throw. A typed router runs its param parser before its route guards, so a redirect declared in a guard never sees the failure and the visitor gets the router’s error screen instead of your site. In TanStack Router that is params.parse running ahead of beforeLoad.

Page URL segment
landing none
details bare id (for example abc123)
search search
payment payment
help help
suggestion-widget widget

Bind the helpers to one strategy with createCorasUrlState, then connect both directions: Coras intents out to your router through createCorasRouting, and router changes back into the mount.

import { mount } from "@coras-io/embed";
import { createCorasRouting, createCorasUrlState } from "@coras-io/embed/url";
const coras = createCorasUrlState({
localeCase: "lower",
currencyInPath: false,
defaultCurrency: (locale) => currencyFor(locale), // your default per locale
});
const app = mount({
container,
page: initialState.page,
params: initialState.params,
config,
...createCorasRouting({
url: coras,
navigate: (href) => router.push(href), // onNavigate: a link/selection -> a new history entry
replace: (href) => router.replace(href), // onStateChange: an in-page change -> replace
}),
});
// When the URL changes, reflect it into the mount.
function onRouteChange(url: string) {
const next = coras.parse(url);
if (!coras.isSame(next, app.state)) {
app.update({
page: next.page,
params: next.params,
// An update merges into the mounted config, so these two keys are enough.
config: { locale: next.locale, currency: next.currency },
});
}
}

coras.isSame skips the app.update() call when the parsed URL already matches the mount’s current app.state, avoiding a redundant re-render. app.update() never emits onNavigate, so it cannot loop back through the router on its own - the guard is purely to skip needless renders and state churn.

createCorasRouting builds the three routing mount options from the same URL helper, so the link a control renders (hrefFor) and the route a click takes (onNavigate) are always the same URL. It returns hrefFor, onNavigate and onStateChange. An intent that carries href is an external link: it gets no hrefFor and opens in a new tab instead of being routed (pass external to change that). Both callbacks also receive the detail the URL was built from, for side effects such as remembering a location. url takes the helper, a strategy object to bind one to, or any object with a build(state) method when your URLs need a shape the strategy cannot express.

The three options are plain functions, so a host can also write them by hand:

const app = mount({
container,
page: initialState.page,
params: initialState.params,
config,
hrefFor: (intent) => (intent.href ? undefined : coras.build(intent)),
onNavigate(intent) {
if (intent.href) window.open(intent.href, "_blank", "noopener,noreferrer");
else router.push(coras.build(intent));
},
onStateChange(state) {
router.replace(coras.build(state));
},
});

A full, framework-neutral integration using the History API: one persistent mount kept in sync with the URL, with onNavigate pushing and onStateChange replacing. It renders against the public sandbox, so it runs as-is. Component frameworks swap the history.* / popstate calls for their router - see the framework examples for that wiring.

import { mount, type CorasApp, type CorasConfig } from "@coras-io/embed";
import { getCurrency } from "@coras-io/embed/helpers";
import { createCorasRouting, createCorasUrlState } from "@coras-io/embed/url";
const container = document.querySelector<HTMLElement>("#coras")!;
// Built once and reused. Locale and currency are patched in from the URL.
const config: CorasConfig = {
apiUrl: "https://sandbox.coras.io",
distributorId: "a8405267cbcf4bd2b70114e618516645",
assetsUrl: "https://assets.sandbox.coras.io/shared",
locale: "en-IE",
currency: "EUR",
};
// The currency a URL without one means: the locale's.
function defaultCurrency(locale: string = config.locale) {
return getCurrency(locale);
}
// One URL strategy shared by build and parse, so they always agree on a URL.
// This is the shape the Coras sites use and the one we recommend: a lower-case
// locale segment and the currency as a query param only when it is not the
// locale's default (/en-ie/abc123, /en-ie/abc123?currency=USD). The SDK default
// (/en-IE/EUR/abc123) and any other strategy stay available.
const coras = createCorasUrlState({
localeCase: "lower",
currencyInPath: false,
defaultCurrency,
});
// Reflect a URL into the mount. Locale and currency travel in the URL, so they
// are patched into config here: the mount switches language and currency only
// when config says so. update() never re-emits onNavigate, so there is no loop.
function applyUrl(href: string): void {
const next = coras.parse(href);
if (coras.isSame(next, app.state)) return;
app.update({
page: next.page,
params: next.params,
config: {
locale: next.locale ?? config.locale,
currency: next.currency ?? defaultCurrency(next.locale),
},
});
}
// The History API is the router: a navigation (link/selection) pushes a new
// URL, an in-page state change (a filter, say) replaces the current one.
function show(href: string, replace: boolean): void {
history[replace ? "replaceState" : "pushState"](null, "", href);
applyUrl(href);
}
// Derive the initial page + params from the URL, so a deep link or refresh lands
// on the right page. One persistent mount for every page - route changes call
// app.update(), so the navbar, footer, and chrome stay put.
const initial = coras.parse(location.href);
const app: CorasApp = mount({
container,
page: initial.page,
params: initial.params,
config: {
...config,
locale: initial.locale ?? config.locale,
currency: initial.currency ?? defaultCurrency(initial.locale),
},
// hrefFor, onNavigate and onStateChange from the same URL helper, so the link
// a card renders is the route a click takes. An external href opens in a new tab.
...createCorasRouting({
url: coras,
navigate: (href) => show(href, false),
replace: (href) => show(href, true),
}),
});
// Back / forward (with a router: its route-change hook): re-read the URL.
addEventListener("popstate", () => applyUrl(location.href));

Every onNavigate intent includes a source field:

  • "embed": navigation started inside a Coras page (a user clicked a result).
  • "host": navigation came from your own app.navigate(page, params, { emitNavigate: true }) call. A plain app.navigate() call does not emit an intent.

Push to your router only for "embed" intents. Ignoring "host" intents prevents Coras from re-driving the router for navigation you already initiated. The helper hands the intent to navigate, so the check goes there:

...createCorasRouting({
url: coras,
navigate: (href, intent) => {
if (intent.source !== "embed") return;
router.push(href);
},
replace: (href) => router.replace(href),
}),

Coras pages navigate through onNavigate, so without more a search engine sees no link between your pages: it follows <a href> and the cards, breadcrumbs, navbar logo, footer help links, the category and “See all activities” buttons and the confirmation’s Help Centre link are buttons. Pass hrefFor and those controls render as real links to the URL you return, so crawlers find every page from the pages that mention it. Build it the same way onNavigate routes it:

const app = mount({
container,
page: initialState.page,
params: initialState.params,
config,
hrefFor: (intent) => (intent.href ? undefined : coras.build(intent)),
onNavigate(intent) {
router.push(coras.build(intent));
},
});

A plain click on such a link still emits onNavigate and does not load the href, so your router keeps handling it. A modified click (new tab, new window) or a middle click opens the href the browser’s way. Return undefined for an intent that should stay a button. Without hrefFor, nothing changes. createCorasRouting returns an hrefFor that matches its onNavigate, so a host that uses it gets the links for free.

Pass a strategy object to createCorasUrlState (or to parseCorasUrl and buildCorasUrl directly) to change how URLs are shaped.

Option Type Default Description
basePath string "" Path prefix with no trailing slash, for example /events.
localeInPath boolean true Put the locale in the path.
currencyInPath boolean true Put the currency in the path. When false, currency is a query parameter.
currencyParam string "currency" Query parameter name for currency when currencyInPath is false.
reservedSegments Record<page, string> see table above Override the path segment for each page.
localeCase "canonical" | "lower" "canonical" Case of the locale segment a built URL writes. Parsing accepts either.
defaultCurrency currency | (locale) => currency none A currency left out of built URLs. A parsed URL without one has currency: undefined, so the host supplies the same default.

The Coras-run sites use a lower-case locale segment and the currency as a query parameter only when it is not the locale’s default, so /en-ie/abc123 and /en-ie/abc123?currency=USD. It is the shape we recommend for a new site; the default and every other combination stay supported, and an existing integration keeps its shape unless it opts in:

const coras = createCorasUrlState({
localeCase: "lower",
currencyInPath: false,
defaultCurrency: (locale) => currencyFor(locale), // your default per locale
});
coras.build({
page: "details",
params: { id: "abc123" },
locale: "en-IE",
currency: "EUR",
});
// "/en-ie/abc123" when currencyFor("en-IE") is "EUR"
coras.build({
page: "details",
params: { id: "abc123" },
locale: "en-IE",
currency: "USD",
});
// "/en-ie/abc123?currency=USD"

For example, basePath: "/events" prefixes every built URL and is stripped on parse:

const coras = createCorasUrlState({ basePath: "/events" });
coras.build({ page: "search", params: {}, locale: "en-IE", currency: "EUR" });
// "/events/en-IE/EUR/search" (default, without basePath: "/en-IE/EUR/search")

A non-empty basePath is what you reach for when Coras is embedded in a larger app: it confines Coras to a /events/*-style sub-tree of the host’s routes, leaving every other route the host owns untouched.

To keep currency as a query parameter:

const coras = createCorasUrlState({ currencyInPath: false });
coras.build({ page: "search", params: {}, locale: "en-IE", currency: "EUR" });
// "/en-IE/search?currency=EUR"
  • Navigating inside a Coras page updates the browser URL through your router.
  • Using browser back and forward, or editing the URL, updates the Coras page.
  • The page does not reload or flicker on "host" navigation, which confirms the isSame guard and the source check are working.

createCorasUrlState(strategy?) returns helpers bound to one strategy:

Method Returns Purpose
parse(url) CorasUrlState Parse a relative or absolute URL into a Coras state.
build(state) string Build a canonical URL from a Coras state.
normalize(state) CorasUrlState Normalize locale and currency aliases and ensure a params object.
isSame(a, b) boolean Compare two states to skip redundant updates.

createCorasRouting({ url, navigate, replace, external? }) returns the hrefFor, onNavigate and onStateChange mount options built from url.build: navigate(href, intent) and replace(href, state) are your router’s push and replace, and external(href, intent) opens an intent with href (by default a new tab with noopener).

The standalone functions parseCorasUrl(url, strategy?) and buildCorasUrl(state, strategy?) take the strategy as a second argument. normalizeCorasUrlState(state) and isSameCorasUrlState(a, b) do not take a strategy.

Use createCorasUrlState(strategy) for the routing loop: it binds one strategy once, so every parse/build/isSame call stays consistent. Reach for the standalone functions for one-off conversions where passing the strategy each time (or none) is simpler.