CSS Route Matching

1. Defining URL patterns in CSS

1.1. Declaring named URL patterns: the @route rule

The @route rule is an at-rule that associates a name with a URL pattern. This name can be referenced in @navigation rules and in :active-navigation() pseudo-classes.

The syntax of the @route rule is described by the <route-rule> production in:

<route-rule> = @route <dashed-ident> { <declaration-list> }

This means that the rule accepts a sequence of descriptors that have the syntax of declarations. However, in valid style sheets the only descriptors must match the <route-descriptor> production below. Any other descriptors are ignored.

<route-descriptor> = <pattern-descriptor> |
                     <init-descriptor> |
                     <base-descriptor>
<pattern-descriptor> = pattern : <url-pattern()>
<init-descriptor> = <init-descriptor-name> : <string>
<init-descriptor-name> = protocol | hostname | port | pathname |
                         search | hash
<base-descriptor> = base-url : stylesheet | document | <url>

If two valid descriptors in a single rule have the same name, the last one is used and the others are ignored. If a rule has both a valid <pattern-descriptor> and a valid <init-descriptor> then it is ignored.

This rule associates an author-defined keyword with a URL pattern, so that any URL that matches one of the URL patterns matches the route named by the keyword.

The @route rule can be defined in one of two ways:

with the pattern descriptor

in this case the URL pattern represented is the result of invoking create a URL pattern for url-pattern() given arg as the argument to the url-pattern() function and baseURLSpecifier as the (optional) value of the rule’s <base-descriptor>.

with the other descriptors named by <init-descriptor-name>

In this case the URL pattern represented is the result of invoking create a URL pattern given input as URLPatternInit constructed from the descriptors and their values. Each dictionary member is given the value of the descriptor with the same name, except the baseURL member is given the result of create a URL for a base descriptor given baseURLSpecifier as the (optional) value of the rule’s <base-descriptor>.

Should this use <dashed-ident>, <custom-ident>, or <ident> for the route names?

Should we use base-url or just base as the descriptor name?

NOTE: The list of allowed init descriptors does not include username or password since they seem unlikely to be useful.

@route --movie-list {
  pattern: url-pattern("/movie-list");
}

@route --movie-list {
  pathname: "/movie-list";
}

NOTE: The bracing syntax also allows for future expansion if needed.

NOTE: Some of the design discussion for this feature has been in w3c/csswg-drafts#12594.

1.2. The url-pattern() function

The url-pattern() function represents a URL pattern, which can be used to match URLs.

<url-pattern()> = url-pattern( <string> )

This function represents the URL pattern resulting from invoking create a URL pattern for url-pattern() with its string argument.

The steps of the create a URL pattern for url-pattern() algorithm, given a string arg and an optional baseURLSpecifier which can be document, stylesheet, or a URL, are:

1. Let baseURL be the result of create a URL for a base descriptor given baseURLSpecifier.

2. Return the result of create a URL pattern given arg, baseURL, and an empty map.

NOTE: This function requires that its argument is quoted. This differs from the url() function, which allows its argument to be quoted or unquoted.

The create a URL for a base descriptor algorithm, given an optional baseURLSpecifier which can be document, stylesheet, or a URL, is:

if baseURLSpecifier is not present or is stylesheet

the style resource base URL of the rule or declaration block containing the url-pattern() function.

if baseURLSpecifier is document

the document base URL of the document

if baseURLSpecifier is a URL

baseURLSpecifier

To serialize a url-pattern() function f, serialize a function f, using serialize a string on the single argument to serialize f’s contents.

NOTE: This is defined this way because URLPattern intentionally does not provide a serialization.

1.3. The <route-location> value type

<route-location> = <route-name> | <url-pattern()> | <url>
<route-name> = <dashed-ident>

A <route-location> is defined to match a URL input if:

the <route-location> is a <route-name>

match a URL pattern is non-null given urlPattern as the URL pattern represented by the @route rule referenced by the name and input as input.

the <route-location> is a <url-pattern()>

match a URL pattern is non-null given urlPattern as the URL pattern represented by the function (see create a URL pattern for url-pattern()) and input as input.

the <route-location> is a <url>

The given URL equals input.

Should it also be possible to reference a name defined in a routemap? See the route matching explainer for details.

2. Conditional rules for navigation queries

2.1. Navigation queries: the @navigation rule

The @navigation rule is a conditional group rule whose condition tests characteristics of the current URL or of the state of navigation between two URLs. These queries are called navigation queries.

Authors can use it to:

• write style sheets that apply to multiple pages but behave somewhat differently between those pages,

• write style sheets that apply to single page applications that change their URL over time, so that style changes when the URL changes, and

• write style sheets that declaratively start view transitions (or make other appropriate style changes) in response to navigations.

The syntax of the condition in the @navigation rule is similar to that defined for <supports-condition> in [CSS-CONDITIONAL-3]. Negation, conjunction, and disjunction are all needed so that authors can specify the interaction of multiple styles in ways that are most intuitive and require the simplest code.

@navigation (at: url-pattern("/")) {
  /* These styles only apply to the site's homepage
     (including any URL with a search or hash). */
}

@route --search-results-page {
  pattern: url-pattern("/search-results");
}
@route --product-page {
  pattern: url-pattern("/product/:id");
}

@navigation (from: --search-results-page) and
            (to: --product-page) {
  /* These styles apply when a navigation is in progress
     from a search results page to a product page (as
     defined by the @route rules above), but not in the
     reverse direction. */
}

@navigation (between: --search-results-page and --product-page) {
  /* These styles apply when a navigation is in progress
     between a search results page and a product page (as
     defined by the @route rules above), in either
     direction. */
}

The syntax of the @navigation rule is:

@navigation <navigation-condition> {
  <rule-list>
}

with <navigation-condition> defined as:

<navigation-condition> = not <navigation-in-parens>
                     | <navigation-in-parens> [ and <navigation-in-parens> ]*
                     | <navigation-in-parens> [ or <navigation-in-parens> ]*
<navigation-in-parens> = ( <navigation-condition> ) | ( <navigation-test> ) | <general-enclosed>
<navigation-test> = <navigation-location-test> |
                    <navigation-location-between-test> |
                    <navigation-type-test> |
                    <navigation-phase-test>

<navigation-location-test> = <navigation-location-keyword> : <route-location>
<navigation-location-keyword> = at | with | from | to

<navigation-location-between-test> =
    between : <route-location> and <route-location>

<navigation-type-test> = history : <navigation-type-keyword>
<navigation-type-keyword> = traverse | back | forward | reload

<navigation-phase-test> = phase : <navigation-phase-keyword>
<navigation-phase-keyword> = loading | ready | committed

Should we use at/with/from/to or current/other/from/to?

The above grammar is purposely very loose for forwards-compatibility reasons, since the <general-enclosed> production allows for substantial future extensibility. Any @navigation rule that does not parse according to the grammar above (that is, a rule that does not match this loose grammar which includes the <general-enclosed> production) is invalid. Style sheets must not use such a rule and processors must ignore such a rule (including all of its contents).

Many of these grammar terms are associated with a boolean result, as follows:

<navigation-condition>

not <navigation-in-parens>

The result is the negation of the <navigation-in-parens> term.

<navigation-in-parens> [ and <navigation-in-parens> ]*

The result is true if all of the <navigation-in-parens> child terms are true, and false otherwise.

<navigation-in-parens> [ or <navigation-in-parens> ]*

The result is false if all of the <navigation-in-parens> child terms are false, and true otherwise.

<navigation-in-parens>

The result is the result of the child subexpression.

<navigation-location-test>

at: <route-location>

The result is true if the current at URL at of the document is non-null and the <route-location> matches at.

with: <route-location>

The result is true if the current with URL other of the document is non-null and the <route-location> matches other.

from: <route-location>

The result is true if the current from URL from of the document is non-null and the <route-location> matches from.

to: <route-location>

The result is true if the current to URL to of the document is non-null and the <route-location> matches to.

<navigation-location-between-test>

between: <route-location> and <route-location>

The result is true if the current from URL from of the document is non-null, the current to URL to of the document is non-null, one of the two <route-location>s matches from, and the other of the two <route-location>s matches to.

<navigation-type-test>

history: traverse

True if the current navigation type is traverse.

history: back

True if the current navigation type is traverse and the current navigation delta is less than 0.

history: forward

True if the current navigation type is traverse and the current navigation delta is greater than 0.

history: reload

True if the current navigation type is reload.

<navigation-phase-test>

phase: loading

Needs to be defined.

phase: ready

Needs to be defined.

NOTE: Only applies to cross-document navigations.

phase: committed

Needs to be defined.

<general-enclosed>

The result is false.

Authors must not use <general-enclosed> in their stylesheets. It exists only for future-compatibility, so that new syntax additions do not invalidate too much of a <navigation-condition> in older user agents.

A document’s navigation API is the result of the following steps on document:

1. Let window be the Window whose associated Document is document, or null if there is no such Window.

2. If window is null, return null.

3. Return window’s navigation API.

The condition of the @navigation rule is the result of the <navigation-condition> in its prelude.

NOTE: Some of the design discussion for this feature has been in w3c/csswg-drafts#12594 and w3c/csswg-drafts#8209.

2.2. The navigation() function for @when

This specification defines an additional function for the @when rule:

navigation() = navigation( <navigation-condition> )

The navigation() function is associated with the boolean result that its contained condition is associated with.

2.3. The navigation() function for if()

This specification defines an additional function for the if() function’s <if-test> production:

navigation() = navigation( <navigation-condition> )

This should probably have a more formal definition of the function, but I can’t find the formal definitions of the existing if() functions to model it after.

3. Pseudo-classes for links

3.1. The ::link-to() pseudo-class

This specification defines a new :link-to() functional pseudo-class that matches link elements that link to a certain URL.

:link-to(url-pattern("/")) {
  font-weight: bold;
}

The :link-to() pseudo-class takes a single argument, a <route-location>, and the pseudo-class matches any element where both:

• the element matches :any-link

• the <route-location> matches the target of the link

3.2. The ::active-navigation() pseudo-class

This specification defines a new :active-navigation() functional pseudo-class that matches link elements that link to a certain URL that is related to a navigation that is currently active.

@view-transition {
  /* allow cross-document view transitions */
  navigation: auto;
}

@route --movie-details-with-id {
  /* match URLs like /en/movie/123 which is the English page
     about a movie with ID 123.  Be careful to specify the
     language part with a "*" but the ID part with a named
     :id parameter so that matching will require equal IDs
     but allow differences of language. */
  pattern: url-pattern("/*/movie/:id");
}

/* capture the overall area representing the movie, and a
   sub-area for its poster image */

/* match an element with class movie-container with a child
   link that links to a movie whose id is the same as the
   movie we are currently navigating to or from.  (lang can
   be different, though.)

   This depends on the --movie-details-with-id route
   declaring the ID but not the language with a named
   parameter, and the use of the 'with' keyword.

   This means that both the of the link and the other URL of
   the current navigation match the URL pattern defined by
   the "@route --movie-details-with-id" rule, and that the
   id named group from both matches be the same.  (However,
   the URLs can be different because the * part of the
   match, containing the language, can be different.)
   */
.movie-container:has(
    > .movie-title:active-navigation(with --movie-details-with-id)) {

  view-transition-name: movie-container;

  > .movie-poster {
    view-transition-name: movie-poster;
  }

  /* leave the default cross-fade animation for both image
     captures */
}

The :active-navigation() pseudo-class takes a single argument, a <active-navigation-condition>, and the pseudo-class matches any element where:

• the element matches :any-link

• the target of the link matches the <active-navigation-condition>, as defined below.

<active-navigation-condition> =
  <navigation-relation>? [ <route-location> | link-href ]?
<navigation-relation> = at | with | from | to

NOTE: The link-href keyword is an explicit way to represent the default, but there is no difference between specifying it explicitly or omitting it.

Should we use at/with/from/to or current/other/from/to?

The active navigation URL for an <active-navigation-condition> is:

If the <navigation-relation> is at

The current at URL of the document

If the <navigation-relation> is with or is omitted

The current with URL of the document

If the <navigation-relation> is from

The current from URL of the document

If the <navigation-relation> is to

The current to URL of the document

An <active-navigation-condition> matches the target linkTarget of the link when the following steps return true:

1. Let navigationURL be the active navigation URL of the <active-navigation-condition>

2. If navigationURL is null, return false.

3. If a <route-location> is present:

   1. Let targetMatchResult be the result of match a URL pattern given urlPattern and linkTarget.

   2. Let navigationMatchResult be the result of match a URL pattern given urlPattern and navigationURL.

   3. If navigationMatchResult or targetMatchResult is null, return false.

   4. For each property prop of URLPatternResult that is a URLPatternComponentResult:

      1. If groups of prop of targetMatchResult is not equal to groups of prop of navigationMatchResult, then return false.

         Need to formally define equality of ordered maps.

   5. Return true.

4. Otherwise:

   1. Return true if linkTarget equals navigationURL.

   2. Return false.

NOTE: Some of the design discussion for this feature has been in w3c/csswg-drafts#13163.

4. Definitions of current navigation state

Both the @navigation rule and the :link-to() pseudo-class rely on the following definitions of current at URL the current with URL, current from URL, and current to URL.

The current from URL of a document is a URL or null. It is defined as follows:

1. If the document’s navigation API of the document is non-null and its transition is non-null, its from entry’s url.

   NOTE: This part is for when the old document in the navigation is still the current document.

2. If the document’s navigation API of the document is non-null, its activation is non-null, the activation’s from is non-null, and the document’s has been revealed is false or was false at the start of the current task, the activation’s from’s url.

   NOTE: This part is for when the new document in the navigation has become the current document.

3. Otherwise, null.

   NOTE: The previous two branches can also produce null results.

The current to URL of a document is a URL or null. It is defined as follows:

1. If the document’s navigation API of the document is non-null and its ongoing navigate event is non-null:

   1. if the pageswap event has fired since that navigation began, and its activation was non-null, and that activation’s entry’s url is non-null, then that url.

      NOTE: This part does expose the result of redirects.

      NOTE: This part is not relevant to normal page rendering. However, it can be relevant to what is rendered when capturing the image for a cross-document view transition.

      Is the final "non-null" check needed?

   2. otherwise, the ongoing navigate event’s destination’s url

      NOTE: This part does not expose the result of redirects.

   This assumes that the ongoing navigate event and the transition have the same lifetime, but this isn’t really true if the event is intercepted. After whatwg/html#11690 / whatwg/html#11692. we could probably define this more like "from" above. But which lifetime is the one we want?

   NOTE: This part is for when the old document in the navigation is still the current document.

2. If the document’s navigation API of the document is non-null and its activation is non-null, the document’s has been revealed is false or was false at the start of the current task, and the activation’s entry’s url.

   NOTE: This part is for when the new document in the navigation has become the current document.

   Does it make sense to expose this when the activation’s from is null, and thus there is no current from URL?

3. Otherwise, null.

   NOTE: The previous two branches can also produce null results.

The above definitions of from and to apparently don’t work right if you start a same-document navigation (e.g., with pushState) in the middle of a cross-document navigation.

The current at URL of a document is a URL or null. It is defined as follows:

1. Write this! (It should be null if there is no active navigation, and the same as the document’s URL if there is.)

The current with URL of a document is a URL or null. It is defined as follows:

1. Write this! (It should be like current to URL and current from URL but always referring to the other Document in the navigation.)

The current navigation type of a document is a NavigationType or null. It is defined as follows:

1. If the document’s navigation API of the document is non-null and its transition is non-null, the transition’s navigationType.

   NOTE: This part is for when the old document in the navigation is still the current document.

2. If the document’s navigation API of the document is non-null and its activation is non-null, the document’s has been revealed is false or was false at the start of the current task, the activation’s navigationType.

   NOTE: This part is for when the new document in the navigation has become the current document.

3. Otherwise, null.

The current navigation delta of a document is a NavigationType or null. It is defined as follows:

1. If the document’s navigation API of the document is non-null and its transition is non-null,

   1. If the transition’s navigationType is not traverse, null.

   2. Otherwise, the transition’s to’s index minus the transition’s from’s index.

   NOTE: This part is for when the old document in the navigation is still the current document.

2. If the document’s navigation API of the document is non-null, its activation is non-null, the activation’s from is non-null, and the document’s has been revealed is false or was false at the start of the current task,

   1. If the activation’s navigationType is not traverse, null.

   2. Otherwise, the activation’s entry’s index minus the activation’s from’s index.

   NOTE: This part is for when the new document in the navigation has become the current document.

3. Otherwise, null.

Generally improve integration with the HTML spec for these definitions, instead of monkeypatching. This includes the interaction with has been revealed and the interaction with the pageswap event, and other things where this section links to non-exported definitions.

Generally figure out if these definitions should care about the ongoing navigate event or the transition.

Privacy Considerations

To be written.

Security Considerations

To be written.