Capture useful UI screenshots from Node.js.

The mental model

DOMShot should not be the brain of your product or writing workflow. The calling agent decides the story, the section, and which visual supports that story. DOMShot provides the eyes and camera: it can inspect visible UI, find likely elements, capture them, style them, and return confidence, warnings, and file paths.

What this feels like in an agent

DOMShot is not just a screenshot command with nicer padding. The useful part is the agent workflow. You can ask for a visual in normal language, and the agent can use DOMShot to inspect the page, choose likely elements, make a contact sheet, capture polished PNGs, and return the file paths with confidence and warnings.

Install

Install the npm package in the project where the agent or script will run. Playwright Chromium is the local browser DOMShot uses for normal public page captures.

npm install @usedomshot/cli
npx playwright install chromium

Expected result: Node can import @usedomshot/cli, and CLI/MCP commands can start a local browser.

Selector mode vs target mode

Use selector when you know the exact CSS selector. This is the precise path. Use target when the agent only knows the meaning of the thing it wants, such as pricing card, download button, or balance card. If both are provided, selector wins. Selector mode stays exact unless verify is enabled; target mode checks nearby crops by default.

Capture one exact element

Use this when you already know the selector. DOMShot opens the URL, waits for that element, captures it, applies the selected preset, and writes the PNG.

import { captureDomshot } from "@usedomshot/cli";

const result = await captureDomshot({
  url: "https://example.com",
  selector: "h1",
  output: "artifacts/example-heading.png",
  preset: "floating"
});

console.log(result.path, result.width, result.height);

Expected output: artifacts/example-heading.png and a result object with path, width, height, selector, fallback status, and warnings if anything needed review.

Capture by target

Use this when an agent can describe the element in normal language. DOMShot scans visible elements, scores likely matches using DOM and visual signals, chooses the best candidate, and then captures that resolved selector.

import { captureDomshot } from "@usedomshot/cli";

const result = await captureDomshot({
  url: "https://example.com",
  target: "pricing card",
  output: "artifacts/pricing-card.png",
  style: "auto"
});

console.log(result.selector, result.verification?.reason, result.style?.reason);

Expected output: a polished PNG, plus the selector DOMShot chose, sanitized target metadata, crop verification metadata, and auto-style reasoning. If the selected element is not right, inspect first or retry with a more specific target.

Smart crop and auto style

Use style: "auto" when the agent wants DOMShot to choose a practical presentation. DOMShot evaluates transparent, light paper, and dark graphite treatments, then returns sanitized style metadata with the selected background, shadow, padding, crop, and reason.

await captureDomshot({
  url: "https://example.com",
  selector: ".pricing-card-title",
  verify: true,
  style: "auto",
  output: "artifacts/pricing-card.png"
});

Use verify: true with an exact selector when the selector may point at inner text and a parent card would be the better crop. Target mode already uses nearby verification by default.

Use an existing Playwright page

Use this when your automation already controls a Playwright page. DOMShot reuses that page instead of opening a new browser. This is useful when your script has already logged in, clicked a tab, or prepared page state.

import { chromium } from "playwright";
import { captureElement } from "@usedomshot/cli";

const browser = await chromium.launch();
const page = await browser.newPage();

try {
  await page.goto("https://example.com");
  await captureElement(page, {
    selector: "h1",
    output: "artifacts/heading.png",
    background: "transparent"
  });
} finally {
  await browser.close();
}

Next step: if the page is private or logged in outside Playwright, use CDP or profile mode from the CLI/MCP troubleshooting docs.

Plan before capture

A plan is a dry run. It helps the agent decide what should be captured before writing final PNG files. Use it for a feature section, blog post, docs page, pricing page, or homepage section when the agent needs to compare candidates and avoid weak visuals.

import { createDomshotPlan } from "@usedomshot/cli";

const plan = await createDomshotPlan({
  url: "https://example.com",
  intent: "homepage feature section",
  target: "feature cards",
  count: 4,
  output: ".domshot/plan.json",
  style: "auto"
});

console.log(plan.shots.map((shot) => ({
  selector: shot.selector,
  suggestedOutput: shot.suggestedOutput,
  decision: shot.decision.decision,
  why: shot.decision.why,
  risks: shot.decision.risks
})));

Expected output: a JSON plan with planned shots, selectors, suggested file names, style suggestions, decisions like use or review, and retry advice. It does not contain screenshot payloads.

Create a shot pack

A shot pack is the higher-level workflow. Use it when the agent needs final image assets for a homepage section, blog post, docs block, pricing page, or social post. It inspects the page, chooses useful candidates, captures PNGs, writes a contact sheet, and produces a sanitized report.

import { createDomshotShotPack } from "@usedomshot/cli";

const pack = await createDomshotShotPack({
  url: "https://example.com",
  intent: "homepage feature section",
  target: "feature cards",
  count: 4,
  outputDir: "artifacts/homepage-shot-pack",
  style: "auto"
});

console.log(pack.contactSheet, pack.report);

Expected output: multiple PNG files, a contact sheet for visual comparison, and a report.json with selected reasons, rejected candidates, confidence, warnings, and style choices.

Plan vs shot pack

Use a plan when the agent should think before writing images. Use a shot pack when you want DOMShot to inspect, plan, capture, and write the full set in one workflow.

Useful options

These are the options most agents need first. Styling options change the finished PNG; discovery options help DOMShot find or prepare the right element.

If a page has a cookie banner, hidden tab, lazy content, or modal, use steps so the page is in the right state before DOMShot inspects it.

Result metadata

Results include file paths, dimensions, selector, fallback status, warnings, crop verification, auto-style reasoning, and sanitized target/candidate metadata. DOMShot does not return cookies, tokens, raw page text, or base64 image payloads in planning metadata.

Next