Skip to content
caliper ui docs
DemoSign inGet Pro

Pro

Scan viewfinder

A camera viewfinder for scanning codes. While searching, four corner brackets breathe over the middle and a line sweeps down; when a code is found they close onto it, then turn green with a tick once read, or shake when it cannot be.

Pro
pnpm dlx shadcn@latest add @caliper/scan-viewfinder

Scan to pay

Point the camera at the code at the till.

Point at the QR code

Installs components/ui/scan-viewfinder.tsxDepends on lucide-reactMotion none in component source

When to use

Use it for

  • QR and barcode scanning for payments, tickets, check-in and pairing.
  • Document capture where the edges are detected.

Skip it when

  • Decorating a static image; it should follow a real scanner's state.
  • Desktop flows without a camera; offer a code to type.

Decisions

Why it is built this way, so you know what to keep when you change your copy.

Behaviour

Brackets tell the state
Breathing means looking, closing on a box means found, green means done and a shake means try again.

Styling

Dims the rest
Everything outside the frame darkens, so the eye goes where the camera is reading.

Usage

Your scanner drives it
Pass the state and, once found, the code's box; each state is announced.

Installation

terminal
pnpm dlx shadcn@latest add @caliper/scan-viewfinder

Adds its 2 files to components/ui/, each with its own stylesheet, and installs their packages. Pro installs with your access token, set up once per project. See Pro access. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage

Import it from your copy of the source. The example behind the preview comes with the source.

example.tsx
import { ScanViewfinder } from "@/components/ui/scan-viewfinder"

The worked example comes with Pro

The 45-line example behind the preview opens here, ready to copy.

  • 602 Pro parts, blocks and page templates, all with source
  • $199 once, with a year of updates. What you have stays yours
  • A full refund within 14 days if it is not for you
Checking your licence…

API reference

ScanViewfinder

component

Also accepts the native props of its root element and a ref.

PropTypeDefaultDescription
children *ReactNode—What the camera sees: a video, an image or a live preview.
state *ScanState—
boxScanBox[0.3, 0.3, 0.4, 0.4]Where the code is once found; the brackets close onto it.
hintstring—Says what to point at, e.g. "Point at the QR code on the receipt".

Accessibility

It exposes status semantics, with aria-hidden kept in step with state. Changes that matter are announced through a live region.

No custom key handling; Tab and the native activation keys do the work.

Motion

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.

All Media examples