CSS selectors for element screenshots: a playground

Ten CSS selectors and what each one captures

A CSS selector is a short pattern that points at elements of a page, and an element screenshot is cropped to the first element the pattern matches. These are the ten examples of the playground, with what each matches on the specimen page and how well it survives a change to the site.

<body>
  <header class="site-header">
    <a class="logo">Harbor</a>
    <nav aria-label="Main">
      <a>Product</a>
      <a>Pricing</a>
      <a>Docs</a>
    </nav>
  </header>
  <main>
    <section class="hero">
      <p class="headline">Reports that write themselves</p>
      <p class="lead">Connect your data and share a live report in minutes.</p>
      <a class="btn">Start free</a>
    </section>
    <section id="pricing">
      <p class="section-title">Pricing</p>
      <div class="cards">
        <article class="card" data-plan="free">
          <strong class="plan">Free</strong>
          <p class="price">$0</p>
        </article>
        <article class="card featured" data-plan="pro">
          <strong class="plan">Pro</strong>
          <p class="price">$19</p>
          <span class="badge">Popular</span>
        </article>
        <article class="card" data-plan="team">
          <strong class="plan">Team</strong>
          <p class="price">$49</p>
        </article>
      </div>
    </section>
    <section class="stats">
      <figure data-testid="chart">
        <svg class="css-1q2w3e" role="img" aria-label="Signups per week">
          <rect class="bar" />
          <rect class="bar" />
          <rect class="bar" />
          <rect class="bar" />
        </svg>
        <figcaption>Signups per week</figcaption>
      </figure>
      <table class="orders">
        <thead>
          <tr>
            <th>Order</th>
            <th>Amount</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>1042</td>
            <td>$120</td>
          </tr>
          <tr>
            <td>1043</td>
            <td>$295</td>
          </tr>
          <tr>
            <td>Total</td>
            <td class="total">$415</td>
          </tr>
        </tbody>
      </table>
    </section>
  </main>
  <footer class="site-footer">
    <p>Made by Harbor</p>
  </footer>
</body>

Which CSS selectors are robust, and which break?

A robust selector keeps pointing at the same thing after the site changes. The scale below orders five kinds of selector from brittle to sturdy by one question: how much reason does the site have to keep this hook as it is? It is reasoning, not a measurement.

What goes wrong with element screenshots, and the fix

An element screenshot fails in six recognisable ways, and each one has a cause you can name. Find the symptom, read the cause, apply the fix. In the drawings the blue frame is the crop and the grey shapes are the page.

• The selector matches nothing

  Causes

  • The element is added by a script after the page has loaded.
  • The element is inside an iframe. An iframe holds a separate document, and a selector run on the outer page does not look into it.
  • The element is inside a shadow DOM, the private tree of a web component. document.querySelectorAll does not find elements in there.

  Fix

  Wait for the element before capturing. For an iframe, capture the iframe element itself, or open the address the frame loads and capture that page. For shadow DOM, use a tool whose selectors pierce open shadow roots, as Playwright does, or select the host element.^[9][10][12]

• It captures the wrong element

  Cause

  • The selector matches several elements and the capture takes the first one in document order, which may be a hidden template, a mobile menu or an earlier card.

  Fix

  Count the matches in the console, then narrow the selector with a parent (#pricing .card), an attribute ([data-plan="pro"]) or :has().^[7]

• The element is cut off at the bottom

  Cause

  • The element is taller than the browser window, and the tool captured only the part that was on screen.

  Fix

  Use a tool that captures the element from the whole document and not from the visible window. If yours does not, make the window taller than the element.

• A header or banner covers part of it

  Cause

  • A sticky header, a cookie banner or a chat bubble is drawn on top of the page, and it was sitting over the element at the moment of capture.

  Fix

  Hide the overlay before the capture with display: none, by its own selector. Hiding is safer than scrolling: the overlay follows the scroll.

• The element is there but empty inside

  Cause

  • Images, a chart or a map inside the element load only when the element scrolls near the screen, or draw themselves a moment after the page loads.

  Fix

  Wait for something that exists only once the content has loaded, such as #chart canvas or .map img, and add a short pause for drawing animations. Scroll through the page first if the content loads on scroll.

• The capture fails although the element exists

  Cause

  • The element is hidden (display: none, a closed menu or tab), or it has no size because everything inside it is positioned outside its box. There is no rectangle to capture.

  Fix

  Open it first with a click, or select the visible element inside or around it. In the console, getBoundingClientRect() on the element shows a width or height of 0 when this is the cause.

Element screenshots with the CurlShot API

curl "https://curlshot.com/api/v1/screenshot?access_key=YOUR_ACCESS_KEY&url=https://example.com&selector=h1&wait_for_selector=h1&hide_selectors=.cookie-bar,%23chat&device_scale_factor=2" \
  --output heading.png

What the selector option does, case by case