CSS @location At-Rule

The @location at-rule defines a named URL pattern that other CSS rules can reference when matching links or page navigation. It is part of the experimental CSS Navigation Module Level 1 and is intended to help developers apply navigation-related styles without relying entirely on JavaScript.

@location Syntax

@location --location-name {
  pattern: url-pattern("/path");
}

The @location at-rule begins with a custom identifier, followed by a block containing descriptors that define a URL pattern.

The custom identifier must begin with two hyphens, such as --home-page or --product-page.

The pattern descriptor uses the proposed url-pattern() function to describe which URLs belong to the named location.

The rule defines a reusable URL pattern. It does not apply styles directly or create a browser navigation event.

How @location Works

The @location at-rule gives a name to a URL pattern so that other CSS features can refer to that pattern.

@location --contact-page {
  pattern: url-pattern("/contact.html");
}

This defines a location named --contact-page that represents the specified URL path.

The name can then be referenced by proposed CSS navigation features, including @navigation and :link-to().

This separates the URL-matching definition from the CSS rules that use it. If a URL pattern changes, the location can be updated without changing every reference to its name.

Experimental Feature: The @location at-rule is defined in an evolving specification. Its syntax and behavior may change before browser implementations become widely available.

Location Descriptors

The draft specification defines descriptors for matching URLs and determining how relative URL patterns are resolved.

Descriptor	Description
`pattern`	Defines a URL pattern using `url-pattern()`.
`protocol`	Matches the URL protocol.
`hostname`	Matches the URL hostname.
`port`	Matches the URL port.
`pathname`	Matches the URL path.
`search`	Matches the URL query string.
`hash`	Matches the URL fragment.
`base-url`	Specifies the base URL used to resolve a URL pattern.

The pattern descriptor provides one way to define a location. Alternatively, URL component descriptors can be used to describe parts of the URL.

@location --contact-page {
  pathname: "/contact.html";
}

This example defines the location using its pathname rather than the pattern descriptor.

The draft does not allow a valid pattern descriptor to be combined with URL component descriptors in the same location rule. A rule containing both forms is ignored.

When multiple valid declarations of the same descriptor appear in one rule, the last declaration takes precedence.

URL Patterns

The proposed url-pattern() function allows a location to describe URLs using patterns rather than requiring every address to be written separately.

Matching a Specific Page

@location --about-page {
  pattern: url-pattern("/about.html");
}

This location identifies the specified page path.

Matching Dynamic Paths

@location --product-page {
  pattern: url-pattern("/products/:id");
}

The :id portion represents a variable path segment, allowing the pattern to describe product pages with different identifiers.

Using a Base URL

@location --documentation {
  pattern: url-pattern("/docs/:page");
  base-url: document;
}

The base-url descriptor controls which URL is used as the base when resolving the pattern. The draft supports document, stylesheet, and a specified URL.

URL pattern matching follows the rules described by the CSS Navigation specification and its referenced URL Pattern API.

The proposed @navigation at-rule can reference named locations to determine whether styles should apply during a particular navigation.

@location --home-page {
  pattern: url-pattern("/");
}
@location --contact-page {
  pattern: url-pattern("/contact.html");
}
@navigation (from: --home-page) and (to: --contact-page) {
  ::view-transition-old(root) {
    animation-duration: 0.3s;
  }
}

This example describes a navigation from the home page to the contact page. The nested CSS rule is intended to apply when the navigation matches the specified conditions.

The from condition identifies the starting location, while the to condition identifies the destination.

The specification also proposes a between condition for matching navigation between two locations in either direction.

@navigation (between: --home-page and --contact-page) {
  ::view-transition-new(root) {
    animation-duration: 0.3s;
  }
}

This condition describes navigation between the two named locations regardless of which page is the starting point.

These examples illustrate proposed syntax. They should not be treated as production-ready browser behavior.

Matching Links with :link-to()

The experimental :link-to() pseudo-class can reference a named location to select links that point to matching URLs.

@location --contact-page {
  pattern: url-pattern("/contact.html");
}
:link-to(--contact-page) {
  color: #0056b3;
  font-weight: bold;
}

In a supporting implementation, links whose destination matches the --contact-page location would receive the specified styling.

This differs from :visited, which concerns whether a link has been visited, and from :hover, which responds to pointer interaction.

The proposed :link-to() selector is based on a link's destination URL rather than its interaction state.

@location Example

The following example defines named locations for a home page and contact page, then uses the experimental :link-to() pseudo-class to describe how matching links could be styled.

HTML

<nav>
  <a href="/">Home</a>
  <a href="/contact.html">Contact</a>
</nav>

CSS

@location --home-page {
  pattern: url-pattern("/");
}
@location --contact-page {
  pattern: url-pattern("/contact.html");
}
nav a {
  color: #333;
  margin-right: 15px;
}
:link-to(--contact-page) {
  color: #0056b3;
  font-weight: bold;
}

Under the proposed behavior, the Contact link would appear blue and bold because its destination matches the --contact-page location.

Browsers without support for these experimental features will ignore the unsupported rules. The ordinary nav a styles remain available as a fallback.

Browser Support

The @location at-rule is experimental and is not a Baseline feature. General browser support has not been established. Check the CSS Navigation Module Level 1 for specification updates and Can I Use? for future compatibility information.

Specifications

The @location at-rule is defined in the draft CSS Navigation Module Level 1 specification. It associates a custom identifier with a URL pattern so the identifier can be referenced in navigation conditions and link-matching selectors.

The module remains under development, and the syntax may change before becoming a stable web platform feature.

CSS Navigation Module Level 1

CSS @location At-Rule