CSS @document At-Rule

CSS @document At-Rule

The @document at-rule conditionally applies CSS rules based on the URL of the document being styled. It was designed to match specific URLs, domains, or URL patterns, but is not supported as a standard feature in mainstream browser stylesheets.

@document Syntax

@document url("https://www.example.com/") {
  body {
    background-color: #f5f5f5;
  }
}

The at-rule begins with @document, followed by one or more URL matching conditions and a block containing CSS rules.

The enclosed rules apply only when the current document's URL matches one of the specified conditions, in implementations that support the feature.

Multiple matching conditions can be separated by commas.

How @document Works

The @document at-rule was proposed as a way to apply CSS to particular documents without adding page-specific classes or changing the stylesheet loaded by each page.

For example, a stylesheet could contain rules that apply only to pages within a particular domain.

@document domain("example.com") {
  h1 {
    color: #0056b3;
  }
}

In an implementation that recognizes this syntax, the heading color would change on matching documents within example.com and its subdomains.

However, ordinary web pages cannot rely on this feature because it is not implemented as an interoperable standard.

URL Matching Functions

The proposed syntax includes functions for matching document URLs.

Matching a URL Prefix

@document url-prefix("https://www.example.com/tutorials/") {
  .page-title {
    color: #006699;
  }
}

This example targets documents whose URLs begin with the specified tutorial directory.

Matching Multiple Conditions

@document domain("example.com"), domain("example.org") {
  body {
    font-family: Arial, sans-serif;
  }
}

The rules are intended to apply when either domain condition matches.

@-moz-document

Firefox historically supported the vendor-prefixed @-moz-document rule. It was used for document-specific styling and was particularly useful in user stylesheets.

@-moz-document url-prefix() {
  body {
    background-color: #fff;
  }
}

Modern Firefox restricts @-moz-document in ordinary web stylesheets. The special url-prefix() form without an argument is retained for Firefox-specific compatibility purposes, while broader document matching remains associated with privileged or user styling contexts.

The vendor-prefixed rule should not be treated as a portable way to target individual pages or websites.

Standard CSS Alternatives

For production websites, use standard CSS selectors or load different stylesheets for different pages instead of relying on @document.

Using a Page Class

Add a class to the document's body element to identify the page.

<body class="tutorial-page">
  <h1>CSS Tutorial</h1>
</body>

Then target the page with a standard CSS selector.

.tutorial-page h1 {
  color: #0056b3;
}

This approach works across modern browsers and provides predictable page-specific styling.

Using a Page-Specific Stylesheet

Another option is to include a stylesheet only on the pages that need it.

<link rel="stylesheet" href="css/tutorial.css">

Both alternatives avoid the compatibility limitations of @document.

@document Example

The following example illustrates how document-specific CSS was intended to work.

@document url-prefix("https://www.example.com/articles/") {
  article {
    max-width: 800px;
    margin: 0 auto;
    line-height: 1.6;
  }
  article h2 {
    color: #0056b3;
  }
}

The rules are intended to apply only to documents with URLs beginning with the specified articles directory. Because standard browser support is unavailable, this example is provided for reference rather than as a working live demonstration.

Browser Support

The unprefixed @document at-rule is not supported as a standard feature in mainstream browsers. Firefox retains restricted support for @-moz-document. For current compatibility information, visit Can I Use? and search for CSS @document.

Specifications

The @document at-rule was described in the CSS Conditional Rules Module Level 3 specification. It is no longer part of the current interoperable CSS Conditional Rules model and should be considered a historical or experimental feature.

CSS Conditional Rules Module Level 3 - Historical Working Draft