Published at
Updated at
Reading time
This post is part of my Today I learned series in which I share all my web development learnings.

Custom properties and CSS parsing are always good for surprises like !important behaving slightly differently or properties being "invalid at computed value time".

Today I discovered yet another surprise โ€” custom properties don't work in combination with the url() function. ๐Ÿ˜ฒ

.something {
  /* this doesn't work */
  --image: "";
  background: url(var(--image));

Roman Dvornov describes the details quite well in a GitHub issue, but let me give you a condensed explanation.

The two modes of url()

Your url()-containing CSS will be parsed differently, depending on how you use url(). There's an old and a newer way:

  • Old: url(
  • Newer: url('') or url("")

The problem of the legacy url() token

And these missing quotes of the old way might seem like a tiny detail, but they affect how your CSS is parsed.

Without quotes, the url() syntax looks like a CSS function, but it isn't. CSS parsers will treat it as a single token, a so-called url-token.

.something {
  background: url(;
  //          \---------------------------/
  //            without quotes this โ˜๏ธ is
  //               a single CSS token

And this entire token from url( to the closing ) enforces parentheses, whitespace characters, single quotes (') and double quotes (") to be escaped with a backslash.

If you're curious, here's how url() is parsed in this scenario.

Parsing algorithm for a url-token

url() with a quoted string, on the other hand, is a normal and flexible CSS function notation, which is parsed part by part and works as expected.

But now, guess what happens when you want to use a custom property in combination with url()?

.something {
  /* this doesn't work */
  --image: "";
  background: url(var(--image));
  //              โ˜๏ธ "No quotes? Cool, that's a url-token!"
  //              ๐Ÿ˜ข "Too bad though, `(` isn't allowed in here..."
  //              โŒ "I'll throw everything away!"

Because there are no quotes, this declaration is parsed as a url-token. And unfortunately, the ( in var(--image) isn't escaped, so the parser throws an error and invalidates the entire CSS declaration.

And this legacy url-token parsing is why you can't use custom variables inside of url().

The solution to work around the legacy url()

How can your work around the url-token problem then?

First, you can restructure your code and move the url() function into the custom property declaration itself. The following work just fine! ๐ŸŽ‰

.something {
  --image: url(;
  background: var(--image);

Additionally, the CSS spec maintainers added a new alias to remove the url-token behavior. The src() notation behaves the same way as url() but without this weird legacy url-token logic.

.something {
  /* this works! (theoretically) */
  --image: "";
  background: src(var(--image));

Unfortunately, no browser supports src() (I couldn't find browser support information but tested current Chrome, Safari and Firefox) yet, so it's time for us to wait. ๐Ÿคทโ€โ™‚๏ธ

CSS parsing and custom properties โ€” always good for a surprise!

If you want to read more about this topic, here are some resources:

Was this TIL post helpful?
Yes? Cool! You might want to check out Web Weekly for more quick learnings. The last edition went out 4 days ago.
Stefan standing in the park in front of a green background

About Stefan Judis

Frontend nerd with over ten years of experience, freelance dev, "Today I Learned" blogger, conference speaker, and Open Source maintainer.

Related Topics

Related Articles