:matches()

The :matches pseudo-class is described as a functional pseudo-class by the official CSS Selectors Level 4 specifications. It doesn’t serve any purpose in itself except making some complex selectors lighter by allowing them to be grouped. In a way, we can think as:matches as syntactic sugar.

Basically it keeps you away from repeating a compound selector when there is only one item that varies. I believe it is not only faster to write but also faster to parse for browsers but I have no solid information about this so as far as I know this pseudo-class does nothing more than helping writing selectors.

Syntax

:matches( selector[, selector]* )

:matches() accepts a list of valid selectors as argument. Like:

:matches(section, article, aside, nav) h1 {
  color: #BADA55;
}

/* Same thing as this... */
section h1,
article h1, 
aside h1,
nav h1 {
  color: #BADA55;
}

It makes some complex selectors a lot easier to write, for example:

:matches(section, article, aside, nav) :matches(h1, h2, h3, h4, h5, h6) {
  color: #BADA55;
}

/* ... which would be the equivalent of: */
section h1, section h2, section h3, section h4, section h5, section h6, 
article h1, article h2, article h3, article h4, article h5, article h6, 
aside h1, aside h2, aside h3, aside h4, aside h5, aside h6, 
nav h1, nav h2, nav h3, nav h4, nav h5, nav h6 {
  color: #BADA55;
}

And less repetitive:

.links:matches(:hover, :focus, :active) {
  color: #BADA55;
}

/* Same as */
.links:hover, .links:focus, .links:active {
  color: #BADA55;
}

Note that :matches() can’t be nested and does not work with :not(). None of the following selectors will work:

/* Doesn't work */
:matches(:not(...))

/* Doesn't work */
:not(:matches(...))

/* Doesn't work */
:matches(:matches(...))

Nerd Alert

The specifications state that combinators (e.g. ~, >…) are not allowed in the passed selector in fast profile, but will be in complex profile. To put it simple, fast profile will be the first (and possible last) implementation of the specifications, while complex profile relates an hypothetical perfect future where performance doesn’t matter much. More information here.

Mimicking behaviour with Sass

It is possible to simulate a similar behaviour with Sass (or any CSS preprocessor for that matter):

$matches: section, article, aside, nav;
$selector: ();

@each $match in $matches {
  $selector: append($selector, $match h1, comma);
}

// section h1, article h1, aside h1, nav h1
#{$selector} {
  color: #BADA55;
}

This creates the equivalent selector of :matches() with a list and a loop. You could even create some sort of function to automate this at a higher level, but that’s out of the scope here.

Browser support

This support chart reflets the old syntax, :any, with their respective prefix. It works the same way, so this article is just named for the final specced version.

Note: since CSS rejects the entire selector when there is a part it doesn’t understand, you have to separate them to make it work everywhere. For instance:

/* This won't work in any browser because
 * Webkit browsers do not know `moz` and
 * Gecko browsers do not know `webkit`
 */
:-webkit-any(a, b) c, 
:-moz-any(a, b) c {
  color: #BADA55;
}

/* This however will work */
:-webkit-any(a, b) c {
  color: #BADA55;
}

:-moz-any(a, b) c {
  color: #BADA55;
}