CSS4 Document Rule: A User’s Guide

Lots of websites have a ton of pages, but typically use just a single stylesheet to dictate the design. This is good practice because it reduces HTTP requests, helping the pages load faster in your browser.

But here’s the catch: not all pages need all the style rules in the stylesheet. So, wouldn’t it be awesome if we could pick and choose style rules for specific pages, all while still using just one stylesheet?

This could become a reality with a new proposed CSS rule called @document. It was originally intended to be part of CSS3, but faced some hurdles and got postponed. Now, it’s expected to be part of CSS Level 4.

Let’s dig into how this works, shall we?

Basic Usage

@document allows us to designate style-rules for only specific pages. As stated in the Proposal, it is primarily designed for User Stylesheet. So, users can do the following to customize their (favorite) websites:

@document domain("facebook.com") {
  body {
    background-color: yellow;
  }
  a {
    color: red;
  }
  img {
    border-radius: 100%;
  }
}

@document domain("twitter.com") {
  body {
    background-color: red;
  }
  a {
    color: pink;
  }
}

You can visit UserStyles.org for some great examples of user stylesheets.

We, as web authors, can also utilize @document to control the styles across our website. Let’s say we want our style-rules to be applied on a particular page on our website. To do that, we can encapsulate the style-rules with @document like so:

@document url("https://www.hongkiat.com/blog/about-us/") {
  h1 {
    font-size: 50em;
    color: green;
  }
  p {
    color: red;
  }
  a {
    color: blue;
  }
}

The difference between domain()(from the first example) and url() is that domain() will affect all the pages that are hosted on the specified domain, whereas url() will only apply the style-rules to the specified URL; the other URLs (or pages) are thus unaffected.

You can use url-prefix() to designate style-rules to a URL that begins with, for example, css.

@document url-prefix("https://www.hongkiat.com/blog/category/") {
  h2 {
    font-family: "Georgia";
  }
  div {
    background-color: blue;
    color: #fff;
  }
}

Using the regexp() function, we can go more in-depth with Regular Expression (Regex). The following example is derived from W3C, and the Regex matches the URL that begins with https://www.w3.org/TR/, followed by 4 numerical digits and ending with 8 numerical digits.

@document regexp("https://www.w3.org/TR/\\d{4}/[^/]*-CSS2-\\d{8}/") {
  body {
    transform: rotate(90deg);
  }
}

Conclusion

Alright, we have seen some usage possibilities of the @document rule. But as mentioned, it is currently on hold for CSS4, and Firefox is the only browser that has implemented it with the @-moz-document prefix. Nonetheless, we will be keeping tabs on the development of the @document rule, and see how it goes in the future.