Background removerPro

The cutout a matting model made, on a transparency checkerboard, with Keep and Remove brushes to fix its edges, edge softness, background swatches, hold to compare, and a PNG export at the image's natural size.

Markdown

On this page

ProThe matte arrives with progress and the background fades away. Brush the edges with Keep and Remove, hold Compare, then export the PNG.

Installation

$ pnpm dlx shadcn@latest add @chatcn-pro/background-remover

Usage

tsx

import { BackgroundRemover } from "@/components/ui/chatcn/pro/background-remover"

<BackgroundRemover
  src={image.url}
  alt={image.alt}
  width={image.width}
  height={image.height}
  mask={job.matteUrl}
  processing={job.status === "running"}
  progress={job.progress}
  onExport={(blob) => upload(blob)}
/>

mask is the matte the model returns: an alpha or black and white PNG, a canvas, ImageData or a vector path. Refinement strokes are stored as vectors in fractions of the image, so the export at the natural size is as sharp as the preview. Without onExport, Export downloads the PNG; the ref's toBlob() gives you the same file for your own flow. Swatches take any CSS color or token and resolve it before export.

Examples

States

ProRemoving with progress, refined edges on white, no subject found, a failed removal, disabled and a broken image.

Props

Prop	Type	Notes
`src`, `alt`	`string`	The canvas is named "Cutout of <alt>"
`width`, `height`, `aspectRatio`	`number`	Frame shape before load and the export size
`mask`	`MaskSource`	The matte from the model
`processing`, `progress`	`boolean`, `number`	A status chip after 300 ms, with real progress when you have it
`error`, `onRetry`	`boolean \| string`, `() => void`	A failed removal with Retry
`tool`, `defaultTool`, `onToolChange`	`"keep" \| "remove"`	Default `remove`
`size`, `defaultSize`, `onSizeChange`	`number`	Brush diameter in px, 6 to 120
`softness`, `defaultSoftness`, `onSoftnessChange`	`number`	Edge softness in px, 0 to 16. Default 1
`background`, `defaultBackground`, `onBackgroundChange`, `backgrounds`	`string`, `{ value, label, color? }[]`	Default transparent, white and black
`defaultStrokes`, `onStrokesChange`	`MaskStroke[]`	`brush` strokes keep, `erase` strokes remove
`onExport`, `filename`	`(blob) => void`, `string`	Default downloads "cutout.png"
`ref`	`{ toBlob, undo, redo, reset }`	For your own export flow
`disabled`, `toolbar`, `footer`		Lock, hide the toolbar, a slot below

Keyboard

Key	Action
`K` or `B`, `R` or `E`	Keep, remove
`[`, `]`	Smaller or larger brush by 4 px; with `Shift`, by 16 px
Hold `\`	See the original
`⌘Z` or `Ctrl+Z`	Undo the last stroke
`⇧⌘Z`, `Ctrl+Y`	Redo
`Delete` on the canvas	Reset the edges to the model's cutout

Accessibility

The canvas is a focusable group named after the image, with a described hint for the brushes and keys. Compare is a button you hold with the pointer, Space or Enter.
Brushing needs a pointer; everything else is a labeled control. Size and edge are sliders that announce pixels, the swatches are a toggle group named by color.
Strokes, undo, reset and export are announced politely. Processing is a status with its progress.
Under forced colors the brush ring hides and the swatches keep a system outline.

Motion

When the matte arrives, the original fades out over 280 ms and leaves the cutout on the checkerboard.
Brushing draws straight onto the canvas with no easing; the ring follows the pointer with transforms only, and the removed area shows faintly while you brush.
Compare swaps instantly, since it is held from the keyboard. Status chips fade in 150 ms.