HTML route-matching syntax

The explainer for route-matching describes the main use cases and features of route matching, but details of the exact syntax remain open.

This is in conjunction with https://github.com/w3c/csswg-drafts/issues/12594, where the CSS syntax is discussed.

Principles / key questions

Format

The route map can be:

• JSON (as in the explainer and in speculation rules)
• JS object building (like in service-worker static routing)
• an xml-like element tree (probably not a contender in 2025)
• Reusing the CSS at-rule syntax

What goes in a single rule

Like in service-worker static routing, a rule has a "condition" that defines whether it matches a URL or a navigation, and a set of descriptors that apply when that condition applies.

A condition tests for:

1. A URLPattern with
2. a navigation affinity for this URL, which can be one of current | other | old | new
3. Scope of the source element or the element being styled

A condition can also be a logical combinator of multiple conditions (or/and/not).

When in HTML, the descriptors are (when considering some future enhancements):

• Name (for logical combinators and for CSS)
• History (push, replace or none)
• Mode (intercept vs. passthrough)
• Auto-patching (a URL?)

When in CSS, the descriptors can be any CSS rule, as the route become a "conditional".
In addition, links can match a particular route.

Querying & composing

There are two main precedences for logical combinators, all seeming relevant:

• CSS conditionals already provide logical combinators (not, and, only, and comma for or).
• Speculation rules & service worker static routing use {not: condition} and {or: [condition, condition]} for combinators.

Event handling

The main events fired for routes are match/unmatch/prepare/cleanup (to be bikeshed).

This applies to a rule after resolving its combinators.

1. JSON with pure-JSON combinators

[
  { "name": "article", "condition": { "urlPattern": { "pathname": "/article/:aid" } } },
  { "name": "content", "condition": { "or": ["article", "feed" ] } }
]

This is pure and consistent with existing route-like capabilities, but is on a different field from CSS.

2. JSON with media-style querying

[
  { "name": "article", "condition": { "urlPattern": { "pathname": "/article/:aid" } } },
  { "name": "content", "condition": { "query": "at article, at feed, to content[aid=foo]"] } }
]

This is a more expressive query syntax, and is consistent with how CSS is going to query for routes.

Also it is a convenient way to register to events in a granular way:

documentOrElement.matchRoute("article[aid=1], feed").addEventListener("prepare", e => { 
  // prepare content
});

3. Allow both

Using or, and and query is not colliding syntactically (though perhaps colliding in terms of mental model). We could potentially allow both?

4. Fully CSS

Allow a CSS like syntax, without it being a style:

@route route-name (from article, to feed, urlpattern(pathname: "/content")) {
  history: push;
  mode: intercept;
}

This is very expressive and aligns with the intention of routes as a UI-first feature, but is not consistent with other "route" related features.

5. JS

Instead of using JSON or CSS, use JS initialization:

documentOrElement.routeMap.add({
  condition, name, history, mode
});

This needs to be in conjunction with resolving the query question.

The main disadvantage of this is that it is not static, and requires running scripts on the page imperatively to make work.

Start with route-matching-explainer.md and the linked CSSWG issue 12594. Compare the JSON, CSS, and JavaScript syntax options described here, including their combinator and event-handling implications. Done would require a resolved syntax direction and corresponding specification work, but this issue does not define that decision.