Skip to content
Browse documentation

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.

Used forObject removalGenerative fillProduct photosAvatar editors

Install with the shadcn CLI

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

Registered the namespace? Then it’s shadcn add @hairline/inpaint-brush. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • 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.

What it handles for you

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.

Instead of wiring upreact-sketch-canvasfabric.jskonvacanvas mask editorbrush tool
  1. 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.

  2. You see what goes

    Painted pixels lift away as grains of their own colour, leaving a hole over a quiet dotted well.

  3. The result fills the hole

    The new image appears through the painted area first, then takes over, so you see exactly what changed.

  4. Undo and Clear

    Undo takes back the last stroke and Clear removes them all; nothing is sent until Fill.

  5. Waits and recovers

    Fill shows its progress while your API works; a thrown error is shown and the mask is kept.

  6. Keyboard path

    Arrow keys move the brush (Shift for bigger steps), Space or Enter paints, Ctrl or Cmd+Z undoes.

Overview

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.

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.

Usage

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.

example.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

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= [10, 18, 30]
[number, number, number]
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".

Accessibility and motion

  • 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.

Requirements

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

Source

components/inpaint-brush.tsx
"use client";/* ───────────────────────────────────────────────────────── * INPAINT BRUSH: paint what to change, get it back filled * * Brush over the part of the picture you want changed: the * paint lifts those pixels away as grains of their own colour, * leaving a hole. Fill sends your API the image's mask (white * where you painted, at the image's own resolution) and waits; * the new image it returns fills in through the hole first, * then takes over. Undo takes back the last stroke; keyboard * users move the brush with the arrows and paint with Space. * ───────────────────────────────────────────────────────── */import * as React from "react";import { LoaderCircle, Undo2, Wand2, X } from "lucide-react";export interface InpaintBrushProps {  src: string;  alt: string;  /** Receives the mask (a PNG, white where painted, black elsewhere, at the image's natural size) and returns the new image's URL. */  onInpaint: (mask: Blob, size: { width: number; height: number }) => Promise<string>;  /** Called with the new image's URL once it has filled in. */  onChange?: (src: string) => void;  /** Brush radii in CSS pixels for Small, Medium and Large. */  sizes?: [number, number, number];  crossOrigin?: "anonymous" | "use-credentials";  labels?: { fill?: string; filling?: string; undo?: string; clear?: string; hint?: string; failed?: string };  /** Size the frame here, e.g. "aspect-square w-80". */  className?: string;}type Dab = { x: number; y: number; r: number };type Grain = { x: number; y: number; vx: number; vy: number; c: string; a: number; s: number };type Dust = { pixels: Uint8ClampedArray | null; w: number; h: number; dpr: number; grains: Grain[]; loop: number };const SIZES: [number, number, number] = [10, 18, 30];const SIZE_NAMES = ["Small", "Medium", "Large"];const MAX_GRAINS = 700;const reducedQuery = "(prefers-reduced-motion: reduce)";const subscribeReduced = (onChange: () => void) => {  const query = window.matchMedia(reducedQuery);  query.addEventListener("change", onChange);  return () => query.removeEventListener("change", onChange);};const useReducedMotion = () => React.useSyncExternalStore(subscribeReduced, () => window.matchMedia(reducedQuery).matches, () => false);/** The part of the image object-fit: cover shows in a w × h box. */function coverCrop(iw: number, ih: number, w: number, h: number) {  const s = Math.max(w / iw, h / ih);  const sw = w / s;  const sh = h / s;  return { sx: (iw - sw) / 2, sy: (ih - sh) / 2, sw, sh, s };}export function InpaintBrush({ src, alt, onInpaint, onChange, sizes = SIZES, crossOrigin, labels, className = "" }: InpaintBrushProps) {  const reduced = useReducedMotion();  const frame = React.useRef<HTMLDivElement>(null);  const photo = React.useRef<HTMLCanvasElement>(null);  const dust = React.useRef<HTMLCanvasElement>(null);  const ring = React.useRef<HTMLDivElement>(null);  const state = React.useRef({    img: null as HTMLImageElement | null,    pixels: null as Uint8ClampedArray | null,    w: 0,    h: 0,    dpr: 1,    strokes: [] as Dab[][],    painting: false,    grains: [] as Grain[],    loop: 0,    cursor: { x: 0.5, y: 0.5 },  });  const [current, setCurrent] = React.useState(src);  const [size, setSize] = React.useState(1);  const [strokes, setStrokes] = React.useState(0);  const [busy, setBusy] = React.useState(false);  const [error, setError] = React.useState<string | null>(null);  const [ready, setReady] = React.useState(false);  const [seenSrc, setSeenSrc] = React.useState(src);  if (src !== seenSrc) {    setSeenSrc(src);    setCurrent(src);  }  /** Draws the picture and every stroke's hole, from scratch. */  const redraw = React.useCallback(() => {    const st = state.current;    const canvas = photo.current;    const ctx = canvas?.getContext("2d");    if (!canvas || !ctx || !st.img) return;    const { w, h, dpr, img } = st;    const c = coverCrop(img.naturalWidth, img.naturalHeight, w, h);    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);    ctx.globalCompositeOperation = "source-over";    ctx.clearRect(0, 0, w, h);    ctx.drawImage(img, c.sx, c.sy, c.sw, c.sh, 0, 0, w, h);    ctx.globalCompositeOperation = "destination-out";    for (const stroke of st.strokes) for (const d of stroke) hole(ctx, d);    ctx.globalCompositeOperation = "source-over";  }, []);  // Load the image, size the canvases, and read its pixels for the grains (when CORS allows).  React.useEffect(() => {    const box = frame.current;    if (!box) return;    let live = true;    const img = new Image();    if (crossOrigin) img.crossOrigin = crossOrigin;    img.src = current;    img.decode().then(      () => {        if (!live) return;        const st = state.current;        st.img = img;        st.w = box.clientWidth;        st.h = box.clientHeight;        st.dpr = Math.min(window.devicePixelRatio || 1, 2);        for (const c of [photo.current, dust.current]) {          if (!c) continue;          c.width = Math.round(st.w * st.dpr);          c.height = Math.round(st.h * st.dpr);        }        st.strokes = [];        redraw();        try {          const ctx = photo.current?.getContext("2d", { willReadFrequently: true });          st.pixels = ctx ? ctx.getImageData(0, 0, photo.current!.width, photo.current!.height).data : null;        } catch {          st.pixels = null;        }        setStrokes(0);        setReady(true);      },      () => live && setError(labels?.failed ?? "The image couldn’t be loaded."),    );    return () => {      live = false;    };  }, [current, crossOrigin, redraw, labels?.failed]);  React.useEffect(() => () => cancelAnimationFrame(state.current.loop), []);  const dab = (x: number, y: number) => {    const st = state.current;    const canvas = photo.current;    const ctx = canvas?.getContext("2d");    if (!ctx || !st.img) return;    const d = { x, y, r: sizes[size] };    st.strokes[st.strokes.length - 1]?.push(d);    ctx.setTransform(st.dpr, 0, 0, st.dpr, 0, 0);    ctx.globalCompositeOperation = "destination-out";    hole(ctx, d);    ctx.globalCompositeOperation = "source-over";    if (!reduced && frame.current && dust.current) emitGrains(st, d, getComputedStyle(frame.current).color, dust.current);  };  const local = (event: React.PointerEvent) => {    const r = frame.current!.getBoundingClientRect();    return { x: event.clientX - r.left, y: event.clientY - r.top };  };  const showRing = (x: number, y: number, on: boolean) => {    const el = ring.current;    if (!el) return;    const r = sizes[size];    el.style.transform = `translate(${x - r}px, ${y - r}px)`;    el.style.width = el.style.height = `${r * 2}px`;    el.style.opacity = on ? "1" : "0";  };  const start = (event: React.PointerEvent<HTMLDivElement>) => {    if (busy || !ready) return;    event.currentTarget.setPointerCapture(event.pointerId);    const st = state.current;    st.painting = true;    st.strokes.push([]);    const p = local(event);    dab(p.x, p.y);  };  const moveTo = (event: React.PointerEvent<HTMLDivElement>) => {    const p = local(event);    showRing(p.x, p.y, event.pointerType === "mouse" && !busy);    if (!state.current.painting) return;    dab(p.x, p.y);  };  const end = () => {    const st = state.current;    if (!st.painting) return;    st.painting = false;    if (st.strokes[st.strokes.length - 1]?.length === 0) st.strokes.pop();    setStrokes(st.strokes.length);  };  const undo = () => {    state.current.strokes.pop();    redraw();    setStrokes(state.current.strokes.length);  };  const clear = () => {    state.current.strokes = [];    redraw();    setStrokes(0);  };  // Keyboard: arrows move the brush, Space or Enter paints, Ctrl/Cmd+Z undoes.  const key = (event: React.KeyboardEvent<HTMLDivElement>) => {    const st = state.current;    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "z") {      event.preventDefault();      undo();      return;    }    const step = event.shiftKey ? 0.08 : 0.025;    const delta = { ArrowLeft: [-step, 0], ArrowRight: [step, 0], ArrowUp: [0, -step], ArrowDown: [0, step] }[event.key];    if (delta) {      event.preventDefault();      st.cursor.x = Math.min(1, Math.max(0, st.cursor.x + delta[0]));      st.cursor.y = Math.min(1, Math.max(0, st.cursor.y + delta[1]));      showRing(st.cursor.x * st.w, st.cursor.y * st.h, true);      return;    }    if (event.key === " " || event.key === "Enter") {      event.preventDefault();      if (busy || !ready) return;      st.strokes.push([]);      dab(st.cursor.x * st.w, st.cursor.y * st.h);      showRing(st.cursor.x * st.w, st.cursor.y * st.h, true);      setStrokes(st.strokes.length);    }  };  /** The mask your API gets: white where painted, black elsewhere, at the image's natural size. */  const exportMask = async () => {    const st = state.current;    const img = st.img!;    const c = coverCrop(img.naturalWidth, img.naturalHeight, st.w, st.h);    const mask = document.createElement("canvas");    mask.width = img.naturalWidth;    mask.height = img.naturalHeight;    const ctx = mask.getContext("2d")!;    ctx.fillStyle = "#000";    ctx.fillRect(0, 0, mask.width, mask.height);    ctx.fillStyle = "#fff";    for (const stroke of st.strokes)      for (const d of stroke) {        ctx.beginPath();        ctx.arc(c.sx + d.x / c.s, c.sy + d.y / c.s, d.r / c.s, 0, Math.PI * 2);        ctx.fill();      }    const blob = await new Promise<Blob | null>((resolve) => mask.toBlob(resolve, "image/png"));    return { blob: blob!, size: { width: mask.width, height: mask.height } };  };  const fill = async () => {    if (busy || !strokes) return;    setBusy(true);    setError(null);    try {      const { blob, size: natural } = await exportMask();      const next = await onInpaint(blob, natural);      const img = new Image();      if (crossOrigin) img.crossOrigin = crossOrigin;      img.src = next;      await img.decode();      await fillIn(img);      setCurrent(next);      onChange?.(next);    } catch (e) {      setError(e instanceof Error && e.message ? e.message : labels?.failed ?? "That didn’t work. Try again.");    } finally {      setBusy(false);    }  };  /** The new image appears through the hole first, then over everything. */  const fillIn = (img: HTMLImageElement) =>    new Promise<void>((resolve) => {      const st = state.current;      const ctx = photo.current?.getContext("2d");      if (!ctx || reduced) return resolve();      const { w, h, dpr } = st;      const c = coverCrop(img.naturalWidth, img.naturalHeight, w, h);      const holes = document.createElement("canvas");      holes.width = Math.round(w * dpr);      holes.height = Math.round(h * dpr);      const hctx = holes.getContext("2d")!;      hctx.setTransform(dpr, 0, 0, dpr, 0, 0);      for (const stroke of st.strokes) for (const d of stroke) hole(hctx, d, "#000");      hctx.globalCompositeOperation = "source-in";      hctx.drawImage(img, c.sx, c.sy, c.sw, c.sh, 0, 0, w, h);      const begin = performance.now();      const step = (now: number) => {        const p = Math.min(1, (now - begin) / 900);        redraw();        ctx.setTransform(1, 0, 0, 1, 0, 0);        ctx.globalAlpha = Math.min(1, p / 0.55);        ctx.drawImage(holes, 0, 0);        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);        if (p > 0.55) {          ctx.globalAlpha = (p - 0.55) / 0.45;          ctx.drawImage(img, c.sx, c.sy, c.sw, c.sh, 0, 0, w, h);        }        ctx.globalAlpha = 1;        if (p < 1) requestAnimationFrame(step);        else resolve();      };      requestAnimationFrame(step);    });  const action = "inline-flex h-8 cursor-pointer items-center gap-1.5 rounded-full px-3 text-[12.5px] font-medium transition-[background-color,opacity,scale] duration-150 active:scale-[0.97] disabled:cursor-default disabled:opacity-40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50";  return (    <div className={`flex [:where(&)]:w-full flex-col gap-2.5 ${className}`}>      <div        ref={frame}        role="application"        aria-label={`${alt}. ${labels?.hint ?? "Paint over what to change. Arrow keys move the brush, Space paints, Ctrl+Z undoes."}`}        tabIndex={0}        onPointerDown={start}        onPointerMove={moveTo}        onPointerUp={end}        onPointerCancel={end}        onPointerLeave={() => showRing(0, 0, false)}        onKeyDown={key}        onBlur={() => showRing(0, 0, false)}        className="relative aspect-square w-full cursor-crosshair touch-none overflow-hidden rounded-[18px] bg-muted text-muted-foreground outline-none select-none focus-visible:ring-2 focus-visible:ring-ring/60"        style={{ backgroundImage: "radial-gradient(color-mix(in oklab, currentColor 26%, transparent) 1px, transparent 1px)", backgroundSize: "10px 10px" }}      >        <canvas ref={photo} aria-hidden="true" className="absolute inset-0 size-full" />        <canvas ref={dust} aria-hidden="true" className="pointer-events-none absolute inset-0 size-full" />        <div ref={ring} aria-hidden="true" className="pointer-events-none absolute top-0 left-0 rounded-full opacity-0 ring-1 ring-background shadow-[0_0_0_2px_color-mix(in_oklab,var(--foreground)_45%,transparent)] transition-opacity duration-150" />        {busy && (          <span className="pointer-events-none absolute bottom-3 left-3 inline-flex h-6 items-center gap-1.5 rounded-full bg-background/90 px-2.5 text-[11.5px] font-medium text-foreground ring-1 ring-border">            <LoaderCircle className="size-3 animate-spin" aria-hidden="true" />            {labels?.filling ?? "Filling"}          </span>        )}      </div>      <div className="flex items-center justify-between gap-2">        <div role="radiogroup" aria-label="Brush size" className="inline-flex h-8 items-center gap-0.5 rounded-full p-0.5 ring-1 ring-border">          {sizes.map((r, i) => (            <button              key={SIZE_NAMES[i]}              type="button"              role="radio"              aria-checked={size === i}              aria-label={`${SIZE_NAMES[i]} brush`}              onClick={() => setSize(i)}              className={`grid h-7 w-8 cursor-pointer place-items-center rounded-full transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${size === i ? "bg-accent text-foreground" : "text-muted-foreground hover:text-foreground"}`}            >              <span className="rounded-full bg-current" style={{ width: 4 + i * 3, height: 4 + i * 3 }} />            </button>          ))}        </div>        <div className="flex items-center gap-1">          <button type="button" onClick={undo} disabled={!strokes || busy} aria-label={labels?.undo ?? "Undo stroke"} className={`${action} w-8 justify-center px-0 text-muted-foreground hover:bg-accent hover:text-foreground`}>            <Undo2 className="size-3.5" aria-hidden="true" />          </button>          <button type="button" onClick={clear} disabled={!strokes || busy} aria-label={labels?.clear ?? "Clear mask"} className={`${action} w-8 justify-center px-0 text-muted-foreground hover:bg-accent hover:text-foreground`}>            <X className="size-3.5" aria-hidden="true" />          </button>          <button type="button" onClick={fill} disabled={!strokes || busy} className={`${action} bg-primary text-primary-foreground hover:bg-primary/90`}>            {busy ? <LoaderCircle className="size-3.5 animate-spin" aria-hidden="true" /> : <Wand2 className="size-3.5" aria-hidden="true" />}            {busy ? labels?.filling ?? "Filling" : labels?.fill ?? "Fill"}          </button>        </div>      </div>      <p className="min-h-4 px-0.5 text-[12px] text-muted-foreground" aria-live="polite">        {error ? <span className="text-red-600 dark:text-red-400">{error}</span> : strokes ? `${strokes} ${strokes === 1 ? "stroke" : "strokes"} to fill` : labels?.hint ?? "Paint over what to change"}      </p>    </div>  );}/** Grains lift out of a dab in the colours that were there (or the text colour when the image can't be read). */function emitGrains(st: Dust, d: Dab, ink: string, canvas: HTMLCanvasElement) {  const room = MAX_GRAINS - st.grains.length;  const W = Math.round(st.w * st.dpr);  const H = Math.round(st.h * st.dpr);  for (let i = 0; i < Math.min(24, room); i++) {    const a = Math.random() * Math.PI * 2;    const r = Math.random() * d.r * 0.85;    const x = d.x + Math.cos(a) * r;    const y = d.y + Math.sin(a) * r;    let c = ink;    if (st.pixels) {      const px = Math.min(W - 1, Math.max(0, Math.round(x * st.dpr)));      const py = Math.min(H - 1, Math.max(0, Math.round(y * st.dpr)));      const k = (py * W + px) * 4;      c = `rgb(${st.pixels[k]},${st.pixels[k + 1]},${st.pixels[k + 2]})`;    }    st.grains.push({ x, y, vx: (Math.random() - 0.5) * 1.4 - 0.3, vy: -0.6 - Math.random() * 1.8, c, a: 0.95, s: 1.8 + Math.random() * 1.4 });  }  if (!st.loop) st.loop = requestAnimationFrame(() => drift(st, canvas));}/** One frame of the grains drifting up and fading; sleeps once they've all gone. */function drift(st: Dust, canvas: HTMLCanvasElement) {  const ctx = canvas.getContext("2d");  if (!ctx) {    st.loop = 0;    return;  }  ctx.setTransform(st.dpr, 0, 0, st.dpr, 0, 0);  ctx.clearRect(0, 0, st.w, st.h);  let keep = 0;  for (const g of st.grains) {    g.x += g.vx;    g.y += g.vy;    g.vy -= 0.045;    g.vx *= 0.985;    g.a -= 0.022;    if (g.a <= 0.02) continue;    ctx.globalAlpha = g.a;    ctx.fillStyle = g.c;    ctx.fillRect(g.x, g.y, g.s, g.s);    st.grains[keep++] = g;  }  ctx.globalAlpha = 1;  st.grains.length = keep;  st.loop = keep ? requestAnimationFrame(() => drift(st, canvas)) : 0;}function hole(ctx: CanvasRenderingContext2D, d: Dab, colour = "#000") {  const g = ctx.createRadialGradient(d.x, d.y, d.r * 0.2, d.x, d.y, d.r);  g.addColorStop(0, colour);  g.addColorStop(0.72, colour);  g.addColorStop(1, "rgba(0,0,0,0)");  ctx.fillStyle = g;  ctx.beginPath();  ctx.arc(d.x, d.y, d.r, 0, Math.PI * 2);  ctx.fill();}

Registry item: /r/inpaint-brush.json