Configuration Reference

This page documents all available options for the peek.config.js configuration file.

Config File Format

Create peek.config.js (or peek.config.mjs) in your project root and export a default object:

export default &#123;
  ignore: [],
  checks: &#123;&#125;,
  severity: &#123;&#125;,
&#125;;

Pass it to peek check with -c:

peek check http://localhost:3000 -c peek.config.js

Top-Level Options

`ignore`

Type: string[] Default: []

CSS selectors for elements to exclude from all checks. Merged with --ignore CLI flags and per-check ignore arrays.

ignore: [
  '.ad-banner',
  '[data-testid="skeleton"]',
  '.cookie-popup',
]

`checks`

Type: ChecksConfig Default: All checks enabled with defaults

Per-check configuration. Each key corresponds to a check name. Set to true (default), false (disabled), or an object with options.

checks: &#123;
  overflow: &#123; horizontal: true, vertical: false &#125;,
  clickability: &#123; checkCorners: true &#125;,
  touchTargets: &#123; minWidth: 44, minHeight: 44 &#125;,
  textOverflow: &#123; allowEllipsis: true &#125;,
  visibility: true,
  viewportMeta: true,
&#125;

`severity`

Type: Partial<Record<CheckName, Severity>> Default: Check-specific defaults

Override the default severity for specific checks. Valid severity values: 'error', 'warning', 'info'.

severity: &#123;
  touchTargets: 'warning',
  textOverflow: 'info',
  overflow: 'error',
&#125;

Check-Specific Options

`checks.overflow`

Type: boolean | OverflowConfig

Detect horizontal overflow causing unwanted scrollbars.

Option	Type	Default	Description
`horizontal`	`boolean`	`true`	Check for horizontal overflow
`vertical`	`boolean`	`false`	Check for vertical overflow
`ignore`	`string[]`	`[]`	Additional selectors to skip

checks: &#123;
  overflow: &#123;
    horizontal: true,
    vertical: false,
    ignore: ['.horizontal-scroll-container'],
  &#125;
&#125;

`checks.clickability`

Type: boolean | ClickabilityConfig

Detect interactive elements covered by other elements.

Option	Type	Default	Description
`selectors`	`string[]`	`['button', 'a', 'input', ...]`	Elements to check
`checkCorners`	`boolean`	`true`	Check corner points in addition to center
`ignore`	`string[]`	`[]`	Additional selectors to skip

Default selectors: button, a, input, select, textarea, [role="button"], [role="link"], [onclick], [tabindex="0"].

checks: &#123;
  clickability: &#123;
    selectors: ['button', 'a', '[role="button"]'],
    checkCorners: true,
  &#125;
&#125;

`checks.touchTargets`

Type: boolean | TouchTargetsConfig

Ensure interactive elements meet minimum touch target size and spacing.

Option	Type	Default	Description
`minWidth`	`number`	`44`	Minimum width in pixels (WCAG 2.5.5)
`minHeight`	`number`	`44`	Minimum height in pixels
`selectors`	`string[]`	`['button', 'a', 'input', ...]`	Elements to check
`ignore`	`string[]`	`[]`	Additional selectors to skip

Default selectors: button, a, input:not([type="hidden"]), select, textarea, [role="button"], [role="link"], [role="checkbox"], [role="radio"], [tabindex="0"].

Spacing check: 8px minimum gap between adjacent interactive elements.

checks: &#123;
  touchTargets: &#123;
    minWidth: 48,
    minHeight: 48,
    ignore: ['.desktop-nav a'],
  &#125;
&#125;

`checks.textOverflow`

Type: boolean | TextOverflowConfig

Detect text clipped or overflowing its container.

Option	Type	Default	Description
`allowEllipsis`	`boolean`	`true`	Skip elements using `text-overflow: ellipsis`
`ignore`	`string[]`	`[]`	Additional selectors to skip

Elements with .truncate, [data-truncate], or .line-clamp classes are always skipped.

checks: &#123;
  textOverflow: &#123;
    allowEllipsis: true,
    ignore: ['.code-block', 'pre'],
  &#125;
&#125;

`checks.visibility`

Type: boolean | VisibilityConfig

Detect interactive elements that are invisible or off-screen.

Option	Type	Default	Description
`selectors`	`string[]`	`['button', 'a[href]', 'input', ...]`	Elements to check
`ignore`	`string[]`	`[]`	Additional selectors to skip

Default selectors: button, a[href], input:not([type="hidden"]), select, textarea, [role="button"].

Elements with aria-hidden="true", .sr-only, .visually-hidden, or [hidden] are always skipped.

checks: &#123;
  visibility: &#123;
    selectors: ['button', 'a[href]', 'input'],
    ignore: ['.off-canvas-menu'],
  &#125;
&#125;

`checks.viewportMeta`

Type: boolean | ViewportMetaConfig

Check for a proper viewport meta tag for mobile rendering.

Option	Type	Default	Description
`ignore`	`string[]`	`[]`	(Not applicable for this check)

checks: &#123;
  viewportMeta: true
&#125;

Complete Example

export default &#123;
  ignore: [
    '.ad-banner',
    '[data-testid="skeleton"]',
    '.cookie-consent',
  ],

  checks: &#123;
    overflow: &#123; horizontal: true, vertical: false &#125;,
    clickability: &#123; checkCorners: true &#125;,
    touchTargets: &#123; minWidth: 44, minHeight: 44 &#125;,
    textOverflow: &#123; allowEllipsis: true &#125;,
    visibility: true,
    viewportMeta: true,
  &#125;,

  severity: &#123;
    touchTargets: 'warning',
    textOverflow: 'warning',
    visibility: 'warning',
  &#125;,
&#125;;

TypeScript Types

If using the programmatic API, import types for config objects:

import type &#123;
  CheckConfig,
  ChecksConfig,
  OverflowConfig,
  ClickabilityConfig,
  TouchTargetsConfig,
  TextOverflowConfig,
  VisibilityConfig,
  ViewportMetaConfig,
  Severity,
&#125; from 'peek';