CSS Route Matching

1. Defining URL patterns in CSS

1.1. 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-or-null input if input is non-null, and:

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.

1.2. Declaring named URL patterns: the @route rule

The @route rule is an at-rule that associates an author-defined 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.

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.

It’s possible that this syntax with init descriptors in the @route rule would make more sense as part of the url-pattern() function (that is, as an alternate syntax for what goes inside the function).

This would also give us the option to remove the braces from the syntax of the @route rule and make it more like @import or @namespace. This does remove a potential future extensibility point, but it could also be added back later if we need it.

Either this rule:

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

or this rule:

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

define an @route rule that associates the name --movie-list with the URL "/movies" resolved relative to the style sheet.

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.3. 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 syntax used in the url-pattern() function follows that of URL Pattern. It is a pattern string directly based on the syntax used by the popular path-to-regexp JavaScript library.

Pattern strings can contain capture groups, which by default match the shortest possible string, up to a component-specific separator (/ in the pathname, . in the hostname).

For example, the pathname pattern "/movies/:id" will match "/movies/123" but not "/movies/123/cast".

A regular expression enclosed in parentheses can also be used instead, so the pathname pattern "/blog/:id(\\d+)" will match "/movies/123" but not "/movies/css".

You may also omit the name of the capture group by using only a regular expression, for example "/blog/(\\d+)".

A group can also be made optional by using the ? modifier or by wrapping it in braces. For example, the patterns "/movies/:id?" and "/movies{/:id}" will match both "/movies" and "/movies/123" (but not "/movies/").

A full wildcard * can also be used to match as much as possible, as in the pattern "/*/movies". This too can be given a name, for example "/*lang/movies".

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:

Let baseURL be the result of create a URL for a base descriptor given baseURLSpecifier.
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

This rule:

@route --movie-detail {
  pattern: url-pattern("/movies/:id");
}

defines an @route rule that associates the name --movie-detail with any URL that matches the URL pattern /movies/:id.

Any of the following URLs (relative to the style sheet) match:

/movies/123
/movies/456
/movies/something

These URLs will not match:

/movies/123/ — The trailing slash is not matched by the pattern
/movies/456/extra — The /extra is not matched by the pattern

To have the --movie-details route match only numeric :id values, define the route eiter as:

@route --movie-detail {
  pattern: url-pattern("/movies/:id(\\d+)");
}

or as:

@route --movie-detail {
  pattern: url-pattern("/movies/(\\d+)");
}

This way, /movies/something won’t be matched by the route.

NOTE: Even though the capture groups are not currently exposed, it is recommended to give the capture groups a name for future use.

Should the default always be stylesheet? For use of url-pattern() in , it’s likely more useful for the base URL to be the document URL rather than the style sheet URL. However, it would be very awkward for url-pattern() to be inconsistent with url().

Also see other proposed uses of URLPattern in CSS in w3c/csswg-drafts issue #10975, for :local-link.

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.

2.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.

A simple example of a :link-to() selector is this one, which matches any links that link to the site’s homepage:

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

Passing in a named route is also possible:

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

:link-to(--homepage) {
  font-weight: bold;
}

Because there is no dynamic part in the homepage URL, you might be tempted to pass in a <url> directly:

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

However, url("/") won’t match URLs such as /#scroll-to-here or /?utm_id=something so it is recommended to use the <url-pattern()> or <route-location> variants, or use the following alternative:

@route --homepage {
  pathname: "/";
  base-url: document;
}

:link-to(--homepage) {
  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

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.

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

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

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

Let navigationURL be the current navigation URL of the document given the <navigation-relation> in <active-navigation-condition> (default with).
If navigationURL is null, return false.
If link-href is present, or a <route-location> is not provided:
1. Return true if linkTarget equals navigationURL; Otherwise false.
If a <route-location> is present:
1. Let targetMatchResult be the result of matching a URL pattern given urlPattern and linkTarget.
2. Let navigationMatchResult be the result of matching 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.

The difference between :link-to() and :active-navigation() is that the latter is only active while a navigation is in progress.

Consider this example:

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

:link-to(--homepage) {
  color: lime;
}

:active-navigation(--homepage) {
  color: hotpink;
}

Links that link to the --homepage get a lime color. When navigating to or from the --homepage, their color changes to hotpink for as long as the animation is active.

Once the navigation has completed, the :active-navigation() selector no longer applies, and those links revert back to lime.

In the following examples, all links that link to the --movie-detail route, get a lime color when a navigation is in progress.

@route --movie-detail {
  pattern: url-pattern("/movies/:id");
}

:active-navigation(--movie-detail) {
  color: lime;
}

By adding the following selectors that use a <navigation-relation>, the behavior changes a bit.

:active-navigation(from --movie-detail) {
  color: hotpink;
}

:active-navigation(to --movie-detail) {
  color: yellow;
}

When navigating from /movies/1 to /movies/2:

Links that link to the --movie-detail route with any :id get a lime color during the navigation.
Links that link to the --movie-detail route whose target is /movies/1 (the “from” page) get a hotpink color during the navigation.
Links that link to the --movie-detail route whose target is /movies/2 (the “to” page) get a yellow color during the navigation.

When navigating from /movies/2 to /:

Links that link to the --movie-detail route with any :id get a lime color during the navigation.
Links that link to the --movie-detail route whose target is /movies/3 (the “from” page) get a hotpink color during the navigation.

When navigating from / to /movies/3:

Links that link to the --movie-detail route with any :id get a lime color during the navigation.
Links that link to the --movie-detail route whose target is /movies/3 (the “to” page) get a yellow color during the navigation.

A an example of the :active-navigation() pseudo-class is this example which creates a view transition between a item in a list that contains a link (in this document) and the details page for that link (in a different document). This transition works even when the navigation is a back/forward navigation and even if the user has used a language selector UI to change the page into a different language (and thus change the URL). The use of the :link-to() pseudo-class ensures that the view transition animations from or to the correct item in the list by matching the relevant parts of the navigation URL to the link URL.

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

@route --movie-detail {
  /* match URLs like /en/movies/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("/*/movies/: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-detail 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-detail" 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-detail)) {

  view-transition-name: movie-container;

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

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

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

2.3. The :trigger-link pseudo-class

This specification defines a new :trigger-link that matches link elements that trigger the current navigation.

The :trigger-link pseudo-class matches any element where both:

the element matches :any-link
the current navigation state is not null, and element is its source element.

should this apply to forms or submit buttons?

A simple example of a :trigger-link selector is this one, which sets the view-transition-name for an image thumbnail that is a child of the link that triggers the current navigation.

:trigger-link .thumb {
  view-transition-name: active-image;
}

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.

The @navigation rule can be used in simple cases to define styles that only affect a particular page:

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

The @navigation rule can also be used to define styles that are used when a certain navigation is in progress. This is particularly useful for defining styles that cause view transitions.

@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>

The result is true if the <route-location> matches current navigation URL of the document given the <navigation-relation>.

<navigation-location-between-test>

between: <route-location> and <route-location>: The result is true if the current navigation URL from of the document given from is non-null, the current navigation URL to of the document to 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 document’s current navigation state’s new index is less than its old index.
history: forward: True if the current navigation type is traverse and the document’s current navigation state’s new index is greater than its old index.
history: reload: True if the current navigation type is reload.

<navigation-phase-test>

The current navigation state is not null, and its phase matches the given phase value.

<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.

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.

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.

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.

4. Processing model

The at rules and pseudo-classes defined in this document rely on the current navigation state.

A navigation state is a struct with the following items:

old URL
new URL: a URL
type: a NavigationType
old index
new index: an integer
phase: `loading`, `ready`, or `committed`.
source element: null or an Element.

To get the of a Document document:

If document is not fully active, return null.
Let navigation be document’s relevant global object’s navigation API.
Let activation be navigation’s activation.
If document has not been revealed:
1. If activation is null, return null.
2. Assert: activation’s entry is not null.
3. Return a new navigation state whose old URL is activation’s from’s url, new URL is activation’s entry’s url, type is activation’s navigationType, old index is activation’s from’s index, new index is activation’s entry’s index, phase is `committed`, and source element is null.
Note: this means that navigations that occur before the page is revealed, e.g. calling pushState() in the head do not reflect in CSS.
Let navigateEvent be the ongoing navigate event of navigation.
Let phase be `loading`.
If navigateEvent is null and navigation’s traversing navigate event is not null:
1. Set navigateEvent to navigation’s traversing navigate event.
2. Set phase to `ready`.
If navigateEvent is null, return null.
Return a new navigation state whose old URL is document’s URL, new URL is navigateEvent’s destination’s url, type is ongoingNavigateEvent’s navigationType, old index is navigation’s current entry’s index, new index is navigateEvent’s destination’s index, phase is phase, and source element is ongoingNavigateEvent’s sourceElement.

To get the current navigation URL given a Document document and a <navigation-relation> relation:

Let state be document’s current navigation state.
If state is null, return null.
Return the result of switching on relation:

to: state’s new URL.
from: state’s old URL.
at: state’s new URL if state’s phase is `committed`; Otherwise state’s old URL.
with: state’s old URL if state’s phase is `committed`; Otherwise state’s new URL.

To get the current navigation type of a document document:

If document’s current navigation state is non-null, return its type.
Return null.

The traversing navigate event is the ongoing navigate event which was reset when the ongoing navigation is set to `traversal`.

Improve integration with the HTML standard, especially the concept of traversing navigate event and unexported definitions.

Privacy Considerations

To be written.

Security Considerations

To be written.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

CSS Route Matching

Abstract

Status of this document

1. Defining URL patterns in CSS

1.1. The <route-location> value type

1.2. Declaring named URL patterns: the @route rule

1.3. The url-pattern() function

2. Pseudo-classes for links

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

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

2.3. The :trigger-link pseudo-class

3. Conditional rules for navigation queries

3.1. Navigation queries: the @navigation rule

3.2. The navigation() function for @when

3.3. The navigation() function for if()

4. Processing model

Privacy Considerations

Security Considerations

Conformance

Document conventions

Conformance classes

Partial implementations

Implementations of Unstable and Proprietary Features

Non-experimental implementations

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

Non-Normative References

Issues Index