Mask overlayPro

One image and its mask shown the five ways editors show a selection: marching ants, a tint, the subject isolated against gray, a solid outline, or the black and white matte a model reads. Takes PNG masks, canvases, ImageData or vector paths.

Markdown

On this page

ProFive objects a segmenter found in one product shot. Pick one, then switch between ants, tint, isolate, outline and the matte.

Installation

$ pnpm dlx shadcn@latest add @chatcn-pro/mask-overlay

Usage

tsx

import { MaskOverlay } from "@/components/ui/chatcn/pro/mask-overlay"

<MaskOverlay
  src={image.url}
  alt={image.alt}
  width={image.width}
  height={image.height}
  mask={segment.maskUrl}
  maskLabel="Shoe"
  defaultMode="ants"
/>

A mask can be the black and white or alpha PNG most segmentation and matting APIs return, a canvas, ImageData, or { path }: an SVG path in fractions of the image, the shape COCO polygons convert to. Vector masks stay sharp at any size; raster masks are traced into an outline with marching squares for the ants and the outline mode. MaskLayer is the overlay alone, for any positioned frame whose media fills it, and useMask loads a mask once for several layers.

Examples

States

ProEvery mode, a black and white PNG mask traced into ants, finding the subject, a failed mask, no selection and a broken image.

Props

Prop	Type	Notes
`src`, `alt`	`string`	The image under the mask
`width`, `height`, `aspectRatio`	`number`	Frame shape before load and the size readout
`mask`	`string \| { path, fillRule? } \| HTMLCanvasElement \| ImageBitmap \| ImageData`	Leave empty for no selection
`maskLabel`	`string`	What is selected, for the readout and screen readers
`mode`, `defaultMode`, `onModeChange`	`"ants" \| "tint" \| "isolate" \| "outline" \| "matte"`	Default `ants`
`modes`	`MaskMode[]`	Which modes the switcher offers. Default all five
`controls`	`boolean`	The mode switcher and the readout. Default true
`color`, `opacity`	`string`, `number`	Tint and outline color. Default the accent token at 0.45
`march`	`boolean \| "auto"`	`auto` marches for 5 s after a change and while hovered
`pending`, `pendingLabel`	`boolean`, `string`	Dims the current mask; a "Finding the subject" chip shows after 300 ms
`error`, `onRetry`	`boolean \| string`, `() => void`	A failed mask with Retry
`emptyHint`, `footer`	`string`, `ReactNode`	The no selection hint, a slot below

Keyboard

Key	Action
`Tab`	Moves to the mode switcher
`←` `→`	Move between modes
`Enter`, `Space`	Show the focused mode

Accessibility

The image keeps its own alt. Every overlay layer is aria-hidden; a polite status says what is selected and how much of the image it covers.
Modes are a toggle group with a hint on each. Isolate and matte change the picture without relying on color.
The readout isolates numbers with bdi, so sizes read correctly right to left.
Under forced-colors: active the overlay hides and the image shows plainly.

Motion

Switching modes crossfades the layers in 150 ms. A new mask appears at once, so a click in a segmenter answers immediately.
Marching ants march for 5 s after the mask changes and while the pointer is over the image, then hold still. Under reduced motion they never march.
The ants animate the dash offset of one small path: paint only, no layout.