ScreenshotHandlerConfig

Where page screenshots are stored, in what format, and what part of the page is captured.

crawler/webJavadoc: ScreenshotHandlerConfig

Notes

Shared by both screenshot handlers — WebDriverScreenshotHandler and PlaywrightScreenshotHandler — so a configuration written for one works for the other.

A screenshot can be written to disk, stored on the document as a field, or both, and targets decides which. Storing images in a field puts the encoded image into the document that goes to your committer, which most indexes are not happy to receive: prefer DIRECTORY, and keep the path in a field with targetDirField when you need to find the file again later.

By default screenshots land in ./screenshots, in dated subdirectories, as PNG.

Examples

YAML

  screenshotHandler:
    targets:
      - DIRECTORY
    targetDir: ./screenshots
    targetDirStructure: URL2PATH
    imageFormat: png
    cssSelector: "main"

JSON

{
  "screenshotHandler": {
    "targets": [
      "DIRECTORY"
    ],
    "targetDir": "./screenshots",
    "targetDirStructure": "URL2PATH",
    "imageFormat": "png",
    "cssSelector": "main"
  }
}

XML

<screenshotHandler>
  <targets>
    <target>DIRECTORY</target>
  </targets>
  <targetDir>./screenshots</targetDir>
  <targetDirStructure>URL2PATH</targetDirStructure>
  <imageFormat>png</imageFormat>
  <cssSelector>main</cssSelector>
</screenshotHandler>

Usage

Full configuration skeleton, with every option and its default

YAML

cssSelector: string
imageFormat: string
targetDir: string
targetDirField: string
targetDirStructure: URL2PATH
targetMetaField: string
targets:
  - METADATA

JSON

{
  "cssSelector": "string",
  "imageFormat": "string",
  "targetDir": "string",
  "targetDirField": "string",
  "targetDirStructure": "URL2PATH",
  "targetMetaField": "string",
  "targets": [
    "METADATA"
  ]
}

XML

<configuration>
  <cssSelector>string</cssSelector>
  <imageFormat>string</imageFormat>
  <targetDir>string</targetDir>
  <targetDirField>string</targetDirField>
  <targetDirStructure>URL2PATH</targetDirStructure>
  <targetMetaField>string</targetMetaField>
  <targets>
    <target>METADATA</target>
  </targets>
</configuration>

Properties

Property	Type	Required	Default
cssSelector	string	No	-
imageFormat	string	No	png
targetDir	string	No	-
targetDirField	string	No	crawler.screenshot-path
targetDirStructure	enum	No	DATETIME
targetMetaField	string	No	crawler.screenshot
targets	enum[]	No	-

Property Details

cssSelector

Capture only the element matching this CSS selector instead of the whole page. Leave blank for the full page.

imageFormat

Image format to write, as an ImageIO format name (png by default, jpg and gif also work). PNG keeps text crisp; JPEG produces smaller files for photographic pages.

targetDir

Directory screenshots are written to when targets includes DIRECTORY. Default is ./screenshots.

targetDirField

Document field that receives the path of the file written to targetDir. Default is document.screenshot-path. This is how a committed document points at its screenshot without carrying the image itself.

targetDirStructure

How subdirectories under targetDir are laid out: DATETIME (the default, 2026/08/11/13/34/12/), DATE (2026/08/11/), or URL2PATH — one directory per URL segment, which keeps a site's structure visible on disk.

Allowed Values

• URL2PATH
• DATE
• DATETIME

targetMetaField

Document field that receives the image itself, Base64-encoded, when targets includes METADATA. Default is document.screenshot.

targets

Where to store the screenshot: DIRECTORY (the default), METADATA, or both.