Find CSS Matches

Given some HTML and CSS, find the selectors that match each element, including partial matches. Uses Puppeteer.

Why?

In web projects, it can be difficult to know what CSS selectors will apply to static HTML, especially with larger stylesheets or third-party CSS. This library makes the relationship between markup and CSS more transparent. When developing HTML, it can show the CSS that will apply to the rendered elements, and it's the core behind jest-css-match-serializer.

const { findMatches } = require('find-css-matches')

const styles = `
  div#target {
    padding: 40px;
  }
  div#not-being-used {
    opacity: .5;
  }
  .class-that-could-exist #target {
    font-size: 18px;
  }
`

const html = `
  <div id="target">
    Using findMatches, we'll get the CSS
    selectors that apply to this element.
  </div>
`

const options = {
  recursive: false,
  includePartialMatches: true,
  formatSelector: (a, b) => [a, b ? `??${b}??` : b]
}

const result = await findMatches(styles, html, options)

result:

{
  matches: [
    {
      selector: 'div#target',
      isPartialMatch: false
    },
    {
      selector: '.class-that-could-exist ??#target??',
      isPartialMatch: true
    }
  ]
}

API

findMatches(styles, html, [options])

Returns a promise that resolves to an object, or an array of objects if the HTML has multiple root elements.

{
  matches: {
    selector: <String>,
    [isPartialMatch]: <Boolean>,
    [media]: <String>,
    [css]: Array<String>
  },
  [children]: Array<Object>,
  [html]: <String>
}

html

type: string

The HTML to search for matches.

styles

type: string | object | array

Either a CSS string, or an object or array of objects that each have a url, path, or content property. Objects are forwarded to Puppeteer#addStyleTag.

options.recursive

type: boolean

default: true

Include matches for the child elements (the returned object will have a children property).

options.includePartialMatches

type: boolean

default: true

Include partial matches.

options.formatSelector

type: function

default: (unmatched, matched) => [unmatched, matched]

When includePartialMatches is true, this can be used to format matching selectors. It should return an array of two strings, which are joined with a single space to create the final selector string.

options.includeHtml

type: boolean

default: false

Include an HTML string for each element that's visited.

options.includeCss

type: boolean

default: false

Include the CSS declarations for each matching selector.

findMatchesFactory(styles, [instanceOptions])

Returns a function where the styles have been partially applied:

findMatches(html, [options])

In this function, the options override the instanceOptions, and each call uses the same Puppeteer instance (unlike the default version, which creates a new instance for each call). This can improve performance, and the async findMatches.close will destroy the Puppeteer instance.

const { findMatchesFactory } = require('find-css-matches')

const findMatches = await findMatchesFactory(styles, options)

const matches1 = await findMatches(html1, {/* local options */})

const matches2 = await findMatches(html2, {/* local options */})

await findMatches.close()

Partial Matching

Partial matches are selectors that could apply to an element. They're useful because selectors can reference siblings and ancestors, but those might be unknown when testing an HTML fragment. Take this example:

const html = `
  <div>
    I am the HTML for a simple component.
  </div>
`

const styles = `
  #id span {
    color: yellow;
  }
  #id div {
    color: purple;
  }
`

We know that #id span will never apply to a div, but #id div might apply, depending on whether or not an ancestor has #id. This means that #id div is a partial match, where #id is the "unmatched" portion and div is the "matched" portion.

Example #1

Using options.includeHtml and options.includeCss:

const styles = `
  @media (max-width: 599px) {
    #parent {
      margin: 20px;
    }
  }
  #parent > span ~ span {
    font-weight: 800;
  }
`

const html = `
  <div id="parent">
    <span>child 1</span>
    <span>child 2</span>
  </div>
`

const options = {
  recursive: true,
  includeHtml: true,
  includeCss: true,
  includePartialMatches: false
}

const result = await findMatches(styles, html, options)

result:

{
  matches: [
    {
      selector: '#parent',
      media: '(max-width: 599px)',
      css: [
        'margin: 20px'
      ]
    }
  ],
  html: '<div id="parent">',
  children: [
    {
      matches: [],
      html: '<span>',
      children: []
    },
    {
      matches: [
        {
          selector: '#parent > span ~ span',
          css: [
            'font-weight: 800'
          ]
        }
      ],
      html: '<span>',
      children: []
    }
  ]
}

Example #2

Partial match examples:

index.css

.abra {
  color: purple;
}

.cadabra {
  color: blue;
}

.abra .cadabra {
  color: magenta;
}

.abra > .cadabra {
  color: red;
}

.abra + .cadabra {
  color: green;
}

.abra ~ .cadabra {
  color: yellow;
}

index.js

const { findMatches } = require('find-css-matches')

const styles = [{ path: './index.css' }]

const html = `
  <div class="cadabra">
    <span class="cadabra">
      The work of magic is this,
      that it breathes and at every
      breath transforms realities.
    </span>
  </div>
`

const options = {
  recursive: true,
  includePartialMatches: true,
  formatSelector: (a, b) => [a, b ? `??${b}??` : b]
}

const result = await findMatches(styles, html, options)

result:

{
  matches: [
    {
      selector: '??.cadabra??',
      isPartialMatch: false
    },
    {
      selector: '.abra ??.cadabra??',
      isPartialMatch: true
    },
    {
      selector: '.abra > ??.cadabra??',
      isPartialMatch: true
    },
    {
      selector: '.abra + ??.cadabra??',
      isPartialMatch: true
    },
    {
      selector: '.abra ~ ??.cadabra??',
      isPartialMatch: true
    }
  ],
  children: [
    {
      matches: [
        {
          selector: '??.cadabra??',
          isPartialMatch: false
        },
        {
          selector: '.abra ??.cadabra??',
          isPartialMatch: true
        }
      ],
      children: []
    }
  ]
}

Matches for the parent element:

<span class="cadabra"> 👈
  <div class="cadabra">

Excluded:

❌ .abra

Full Matches:

✅ .cadabra

Partial Matches:

✅ .abra .cadabra

✅ .abra > .cadabra

✅ .abra + .cadabra

✅ .abra ~ .cadabra

Matches for the child element:

<div class="cadabra">
  <span class="cadabra"> 👈

Partial matching for chidren is more restricted, because the parent and siblings are known elements, so there's less ambiguity.

Excluded:

❌ .abra

❌ .abra > .cadabra

❌ .abra + .cadabra

❌ .abra ~ .cadabra

Full Matches:

✅ .cadabra

Partial Matches:

✅ .abra .cadabra

See Also:

jest-css-match-serializer - take snapshots of the CSS that applies to an HTML snippet