Scan Frame

Pro

Camera viewfinder overlay with a cutout sized for QR codes, documents, ID cards or barcodes. A soft line of light glows in QR and barcode frames, and the corners close into a green outline on a match.

Preview

Installation

npx @lumioui/cli add pro/scan-frame

Usage

import { ScanFrame } from "@/components/ui/scan-frame/scan-frame";
<ScanFrame />

Examples

Barcode strip

A pantry tracker adding groceries by barcode.

Document edges

An expense app capturing a café receipt.

ID card

Identity verification in a banking app.

QR check-in

Door staff checking guests into a supper club.

API reference

Prop Type Default
shape ScanFrameShape

Cutout proportions. Default "square".

"square"
aspectRatio number

Override the cutout's width / height ratio.

—
widthRatio number

Cutout width as a share of the frame width (0–1).

—
radius number

Cutout corner radius in px.

—
lift number

Lifts the cutout above centre by this share of the frame height. Default 0.06.

0.06
state ScanFrameState

"scanning" breathes the line; "success" locks; "error" shakes. Default "scanning".

"scanning"
hint string

Guide copy under the cutout — change it with the state.

—
scanLine boolean

Draw the breathing scan line while scanning. Default true for square / strip.

—
showBadge boolean

Pop a check / cross badge in the cutout on success / error. Default false — the closing outline and the light are the result.

false
result React.ReactNode

The card the cutout becomes after a lock has held (700ms) — e.g. the unlocked bike or the matched item. It grows from the cutout into a sheet at the bottom and its content switches on.

—
onSettled () => void

Fires once a lock has held (700ms).

—
haptics boolean

Fire success / error haptics when the state lands. Default true.

true
header React.ReactNode

Chrome floating at the top over the mask (close, title, torch).

—
footer React.ReactNode

Chrome floating at the bottom over the mask (shutter, manual entry).

—
scanLineClassName string

Classes for the scan line (colour). Default white.

—
className string —
children React.ReactNode

The camera feed or a placeholder — fills the frame under the mask.

—