# Inpaint brush

> Paint over what to change: the pixels lift away as grains, Fill sends your API a real mask, and the result fills in through the hole.

The mask editor every inpainting feature needs, built around the moment you paint. Brush over the part of the picture you want changed and those pixels lift away as grains of their own colour, leaving a hole you can see through. Fill exports a proper mask (a PNG, white where you painted and black elsewhere, at the image’s own resolution, which is what inpainting APIs expect) and waits for your onInpaint to return the new image; it then fills in through the hole first and takes over the whole frame. Brush sizes, Undo for the last stroke, Clear, and a keyboard path: arrows move the brush, Space paints, Ctrl+Z undoes.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/inpaint-brush.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): none
- Docs and live preview: https://hairlineui.com/ui/inpaint-brush
- Registry item (source): https://hairlineui.com/r/inpaint-brush.json

## Usage

```tsx
import { InpaintBrush } from "@/components/inpaint-brush";

<InpaintBrush
  src={image.url}
  alt={image.prompt}
  onInpaint={async (mask) => {
    const body = new FormData();
    body.append("mask", mask);
    const res = await fetch(`/api/images/${image.id}/inpaint`, { method: "POST", body });
    return (await res.json()).url;
  }}
  className="w-96"
/>
```

## With an inpainting endpoint

Send the mask and a prompt to your server, which calls the model with the original image, and keep the new URL in your state.

```tsx
"use client";
import * as React from "react";
import { InpaintBrush } from "@/components/inpaint-brush";

export function Retouch({ image }: { image: { id: string; url: string; prompt: string } }) {
  const [url, setUrl] = React.useState(image.url);
  const [prompt, setPrompt] = React.useState("");
  return (
    <div className="grid w-96 gap-3">
      <InpaintBrush
        src={url}
        alt={image.prompt}
        crossOrigin="anonymous"
        onChange={setUrl}
        onInpaint={async (mask, size) => {
          const body = new FormData();
          body.append("image", url);
          body.append("mask", mask, "mask.png");
          body.append("prompt", prompt || "remove the painted area");
          body.append("width", String(size.width));
          body.append("height", String(size.height));
          const res = await fetch("/api/inpaint", { method: "POST", body });
          if (!res.ok) throw new Error("The model couldn’t fill that. Try a smaller area.");
          return (await res.json()).url;
        }}
      />
      <input value={prompt} onChange={(e) => setPrompt(e.target.value)} placeholder="What should go there?" />
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` | – | The image to paint on. Shown square, cropped to cover. |
| `alt` | `string` | – | The image’s text alternative; it is part of the canvas’s label. |
| `onInpaint` | `(mask: Blob, size: { width, height }) => Promise<string>` | – | Gets the PNG mask (white where painted) at the image’s natural size and returns the new image’s URL. Throw to show a message. |
| `onChange` | `(src: string) => void` | – | Called with the new image’s URL once it has filled in. |
| `sizes` | `[number, number, number]` | `[10, 18, 30]` | Brush radii in CSS pixels for Small, Medium and Large. |
| `crossOrigin` | `"anonymous" \| "use-credentials"` | – | Set it when your image host sends CORS headers, so the grains carry the real colours. |
| `labels` | `{ fill?, filling?, undo?, clear?, hint?, failed? }` | – | Words for the toolbar and the hint line. |
| `className` | `string` | – | Width of the editor, e.g. "w-96". |

## States

- **painting**: Each dab punches a feathered hole (Small 10px, Medium 18px, Large 30px radius) and lifts up to 24 grains of the colours under it, which drift up and fade in about 0.7s. A ring shows the brush under a mouse pointer.
- **filling**: Fill turns to Filling with a spinner, and the frame shows the same tag, while onInpaint runs.
- **filled**: The new image fades in through the holes over 0.5s, then over the whole frame over 0.4s; onChange is called with its URL and the strokes are cleared.
- **failed**: The error’s message is shown in red under the toolbar; the strokes stay so Fill can be tried again.
- **reduced motion**: No grains, and the new image replaces the old one in place.

## What it handles

Most mask editors paint a red overlay and leave you to export the mask, scale it to the image and match what the API expects.

- **A mask your API accepts**: onInpaint gets a PNG Blob, white where painted, at the image’s natural size, mapped through the frame’s crop.
- **You see what goes**: Painted pixels lift away as grains of their own colour, leaving a hole over a quiet dotted well.
- **The result fills the hole**: The new image appears through the painted area first, then takes over, so you see exactly what changed.
- **Undo and Clear**: Undo takes back the last stroke and Clear removes them all; nothing is sent until Fill.
- **Waits and recovers**: Fill shows its progress while your API works; a thrown error is shown and the mask is kept.
- **Keyboard path**: Arrow keys move the brush (Shift for bigger steps), Space or Enter paints, Ctrl or Cmd+Z undoes.

## Replaces

react-sketch-canvas, fabric.js, konva, canvas mask editor, brush tool

## Where it fits

- **Object removal**: Paint over a person, a sign or a stain and get the photo back without it.
- **Generative fill**: Mark the area to regenerate from a prompt.
- **Product photos**: Clean a background or remove a reflection before export.
- **Avatar editors**: Fix a detail in a generated portrait.

## Notes

- The canvas is role="application" with a label that explains the keys; the brush sizes are a radiogroup, and the line under the toolbar is a polite live region.
- Strokes are kept as dabs in frame coordinates and replayed for Undo, Clear and the mask, so the mask always matches what you see.
- Painting without CORS still works and the mask is still exported; only the grains fall back to the text colour.
- Grains are capped at 700 and drawn on one canvas only while any are moving.
- Under reduced motion there are no grains and the new image appears in place.

License: MIT (https://hairlineui.com/license#components)
