Ladle

Visual regression testing for your Ladle components.

Prerequisites

npm install -g @pxdiff/cli
npx ladle build

Local Development

One-time setup — authenticate and link your project:

pxdiff login
pxdiff project set myorg/myproject

Capture and diff your Ladle build:

pxdiff ladle ./build --local
pxdiff diff

Open the diff URL from the output to review changes.

CI

Create an API key for your project and set it as a repository secret.

.github/workflows/visual.yml

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

      - run: |
          pxdiff ladle ./build
          pxdiff diff
        env:
          PXDIFF_API_KEY: ${{ secrets.PXDIFF_API_KEY }}

GitHub Action

For a simpler setup, use the pxdiff/ladle action which handles install, capture, and diff in one step:

- name: Build Ladle
  run: npx ladle build

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

Partial Builds

Filter to specific stories to speed up local iteration:

pxdiff ladle ./build --local --filter "Badge*"
pxdiff diff

The --filter flag accepts glob patterns. Only matching stories are captured and diffed.

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.