Ladle GitHub Action

The pxdiff/ladle GitHub Action uploads a Ladle build, discovers stories, captures screenshots, and diffs them against baselines — all in one step.

Quick Start

.github/workflows/visual.yml

name: Visual Regression
on: pull_request

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build Ladle
        run: npx ladle build

      - name: pxdiff Visual Regression
        uses: pxdiff/ladle@v0
        with:
          api-key: ${{ secrets.PXDIFF_API_KEY }}
          build-dir: ./build

Inputs

Input	Required	Default	Description
api-key	yes		pxdiff API key
build-dir	yes		Path to the Ladle build directory
suite	no	"default"	Suite name for grouping snapshots
auto-baseline	no	"false"	Set baselines from captured screenshots (no diff)
auto-approve	no	"false"	Run diff and automatically approve all changes and set baselines
threshold	no		Diff threshold 0.0–1.0
filter	no		Glob pattern to filter stories
api-url	no	"https://pxdiff.com"	pxdiff API URL
cli-version	no	(set at publish)	@pxdiff/cli version range to install

Outputs

Output	Description
diff-url	URL to the diff review page
status	"passed" or "failed"
changed	Number of changed snapshots
new	Number of new snapshots
capture-id	Capture ID
diff-id	Diff ID

Examples

Basic Ladle

- name: pxdiff
  uses: pxdiff/ladle@v0
  with:
    api-key: ${{ secrets.PXDIFF_API_KEY }}
    build-dir: ./build

With Suite and Filtering

- name: pxdiff
  uses: pxdiff/ladle@v0
  with:
    api-key: ${{ secrets.PXDIFF_API_KEY }}
    build-dir: ./build
    suite: design-system
    filter: "Badge*"
    threshold: "0.1"

Auto-Baseline on Main

Use auto-baseline to set baselines from captured screenshots without diffing. Useful for initial setup or on merge to the default branch:

- name: pxdiff
  uses: pxdiff/ladle@v0
  with:
    api-key: ${{ secrets.PXDIFF_API_KEY }}
    build-dir: ./build
    auto-baseline: "true"

Auto-Approve on Main

Use auto-approve to run the diff and automatically approve all changes, setting new baselines. Unlike auto-baseline, this still creates a diff so you can see what changed:

- name: pxdiff
  uses: pxdiff/ladle@v0
  with:
    api-key: ${{ secrets.PXDIFF_API_KEY }}
    build-dir: ./build
    auto-approve: "true"

Full Workflow

A complete workflow that builds Ladle, runs visual regression, and requires approval:

name: Visual Regression
on: pull_request

jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm

      - run: npm ci
      - run: npx ladle build

      - name: pxdiff Visual Regression
        id: pxdiff
        uses: pxdiff/ladle@v0
        with:
          api-key: ${{ secrets.PXDIFF_API_KEY }}
          build-dir: ./build
          suite: ladle

How It Works

The action runs these steps:

1. Install CLI — installs @pxdiff/cli globally (skipped if already available)
2. Upload & Capture — runs pxdiff ladle <build-dir> which uploads the Ladle build, discovers stories, and captures screenshots
3. Diff — runs pxdiff diff to compare against baselines (skipped when auto-baseline is true; runs with --auto-approve when auto-approve is true)
4. Report — parses JSON output and sets GitHub Actions outputs

The action automatically detects the branch and commit from the GitHub Actions environment. No additional git configuration is needed.

Per-Story Parameters

Control capture behavior per-story using the meta.pxdiff field:

export const MyStory = () => <Component />;
MyStory.meta = {
  pxdiff: {
    delay: 500,
    selector: ".wrapper",
    cropToViewport: true,
    ignoreSelectors: [".timestamp"],
    disable: false,
  },
};

See the CLI reference for all pxdiff ladle options.