Layout Checks

peek includes 6 automated layout checks that detect common UI issues. These checks run in a real browser using Puppeteer, inspecting the DOM and computed styles of every relevant element.

Available Checks

overflow

Detects horizontal overflow that causes unwanted scrollbars. Compares document.documentElement.scrollWidth to the viewport width, then identifies the elements responsible for the overflow.

Severity: error

Common causes: Fixed widths wider than viewport, 100vw without accounting for scrollbar, negative margins.

Config options:

overflow: {
  horizontal: true,   // Check horizontal overflow (default: true)
  vertical: false,     // Check vertical overflow (default: false)
  ignore: ['.wide-table']  // Additional selectors to skip
}

clickability

Detects interactive elements (buttons, links, inputs) that are covered by other elements and cannot be clicked. Uses elementFromPoint() at the center and four corners of each interactive element to determine if another element is on top.

Severity: error

Common causes: Overlapping elements, modals/overlays, incorrect z-index stacking.

Config options:

clickability: {
  selectors: ['button', 'a', 'input'],  // Elements to check
  checkCorners: true,                     // Check corner points (default: true)
  ignore: ['.overlay-trigger']
}

touch-targets

Ensures interactive elements meet minimum touch target size (44x44px by default, per WCAG 2.5.5) and have adequate spacing (8px gap) between adjacent targets.

Severity: warning

Common causes: Small icon buttons, tightly packed navigation links, inline links without padding.

Config options:

touchTargets: {
  minWidth: 44,        // Minimum width in pixels
  minHeight: 44,       // Minimum height in pixels
  selectors: ['button', 'a', 'input'],
  ignore: ['.desktop-only']
}

text-overflow

Detects text that overflows or is clipped by its container. Compares scrollWidth/scrollHeight to clientWidth/clientHeight for text-containing elements. Elements with text-overflow: ellipsis, .truncate, or .line-clamp classes are skipped by default.

Severity: warning

Common causes: Dynamic content in fixed containers, long unbreakable strings, internationalized text that is longer than the English source.

Config options:

textOverflow: {
  allowEllipsis: true,   // Skip elements using text-overflow: ellipsis (default: true)
  ignore: ['.code-block']
}

visibility

Detects interactive elements that are invisible or off-screen. Checks for display: none, visibility: hidden, opacity: 0, zero-size elements, off-screen positioning, and clip-path clipping. Elements with aria-hidden="true", .sr-only, or .visually-hidden are skipped.

Severity: warning

Common causes: Forgotten hidden elements, off-screen positioning for focus traps, incorrect CSS.

Config options:

visibility: {
  selectors: ['button', 'a[href]', 'input:not([type="hidden"])'],
  ignore: ['.mobile-menu']
}

viewport-meta

Checks that the page has a proper <meta name="viewport"> tag for mobile rendering. Flags missing viewport tags, missing width=device-width, and accessibility-hostile settings like user-scalable=no and maximum-scale=1 (WCAG 1.4.4 violations).

Severity: warning

Config options:

viewportMeta: {
  ignore: []  // No element-level ignore for this check
}

Running Specific Checks

Use --only to run a subset of checks:

peek check http://localhost:3000 --only overflow,clickability

Valid check names: overflow, clickability, touch-targets (or touchTargets), text-overflow (or textOverflow), visibility, viewport-meta (or viewportMeta).

Ignoring Elements

Three ways to exclude elements from checks:

1. HTML attribute: Add data-peek-ignore to the element
2. CLI flag: --ignore ".selector1,.selector2"
3. Config file: Set the ignore array in peek.config.js

Output Formats

Checks support three output formats via --format:

• text (default) – Human-readable colored output with fix hints
• json – Structured JSON with full issue details, suitable for programmatic consumption
• junit – JUnit XML for CI/CD integration (Jenkins, GitHub Actions, etc.)

Exit Codes

Use --fail-on to control when peek exits with an error:

peek check http://localhost:3000 --fail-on error    # Default: only errors cause failure
peek check http://localhost:3000 --fail-on warning   # Warnings also cause failure