The @document CSS at-rule is used to specify style rules that apply only to certain pages of a document.
In other words, it allows you to specify a set of styles that will be applied only to certain pages of a website that have a URL that you specify.
Using @document, you can restrict a set of style rules to a page whose URL matches a URL that you specify in the @document declaration using the url() function:
@document url('http://mywebsite.com/about-me.html') {
/* styles applicable to the page that has the specified URL */
}
You can also restrict the set of style rules to a set of pages whose URL starts with a specified prefix, using the url-prefix() function:
@document url-prefix(http://mysite.com/blog/) {
/* styles applied to all pages that start with the specified URL */
}
You may want to specify styles that are applicable only to a set of pages whose URL is on a specific domain. You can do that using the domain() function:
@document domain(codrops.com) {
/* styles applied to all pages belonging to the specified domain name */
}
In addition to being able to specify page URLs based on exact URLs, URLs starting with a specific prefix, and URLs belonging to a specified domain name, you can also use the regexp() function to provide a regular expression that is used to determine pages that the styles apply to based on whether or not their URL matches the regular expression.
@document regexp("https:.*") {
/* styles are applicable to any page that starts with 'https:' */
}
Trivia & Notes
The W3C specification states that the main use case of @document is for user-defined style sheets, but this at-rule can be used on author-defined style sheets too. It is generally useful for dealing with third-party content, where specifying styles based on the markup may not be possible.
The function of @document may be substituted with other methods such as providing per-page class names (for example adding a class name to the <body> of a page and then styling that class in the style sheet), or adding inline styles to a page inside a <style> block. However, when the content of the page cannot be modified, or when changing styles for a big number of pages is a daunting task, it’s rather much easier to apply styles to specific pages using the @document rule. It also allows you to create modular styles that you can reuse on different pages, simply by specifying a URL in the @document declaration, without having to resort to the markup in any way, thus also allowing you to separate the styles and markup concerns.
Official Syntax
The @document declaration starts with the @document word, followed by one or more comma-separated list of the four functions: url(), url-prefix(), domain(), and regexp(), followed by a pair of curly braces that will enclose a set of style rules.
@document url(...) {
}
/* or */
@document url-prefix(...) {
}
/* or */
@document domain(...) {
}
/* or */
@document regexp("...") {
}
/* or (multiple functions) */
@document @domain(..), regexp("..") {
/* styles apply to pages belonging to the domain name specified, and whose URL matches the provided regular expression */
}
@document url-prefix(..), domain(..), regexp("...") {
/* styles apply to pages belonging to the domain name specified, and whose URL starts with the specified prefix and also matches the provided regular expression */
}
/* etc. */
The values provided to the url, url-prefix, and domain() functions can be enclosed in single or double quotation marks, but they don’t have to be. Values provided to the regexp() function must be wrapped in quotation marks.
Escaped values provided to the
(MDN)
regexp() function must be escaped from the CSS. For example, a . (period) matches any character in regular expressions. To match a literal period, you would first need to escape it using regular expression rules (to \.), then escape that string using CSS rules (to \\.).
Values
- url()
-
Styles inside the
@documentblock will be applied to a page whose URL matches the URL provided to theurl()function. - url-prefix()
-
Styles inside the
@documentblock will be applied to a page whose URL starts with the value provided to theurl-prefix()function. - domain()
-
Styles inside the
@documentblock will be applied to any page whose URL is on the domain provided to thedomain()function. - regexp()
-
Styles inside the
@documentblock will be applied to any page whose URL matches the regular expression provided to theregexp()function.
Examples
In the following example, the Regex matches the URL that begins with http://www.w3.org/TR/, followed by four numerical digits and ending with eight numerical digits.
@document regexp("http://www.w3.org/TR/\\d{4}/[^/]*-CSS2-\\d{8}/") {
h1 {
color: maroon;
}
}
The following examples applies to heading styles for all pages within the blog subdirectory of a website:
@document url(http://somewebsite.com/blog) {
h1 {
font-size: 2.5em;
color: #111;
}
}
Browser Support
The @document at-rule is currently only supported in Firefox prefixed with the -moz- prefix (@-moz-document).
