# Scan Frame

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.

> Composed · Pro · Mobile-Native — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pro/scan-frame
```

## Import

```tsx
import { ScanFrame } from "@/components/ui/scan-frame/scan-frame";
```

## Variants

- `barcode` — Barcode strip: `npx @lumioui/cli add pro/scan-frame-barcode`
- `document` — Document edges: `npx @lumioui/cli add pro/scan-frame-document`
- `id-card` — ID card: `npx @lumioui/cli add pro/scan-frame-id-card`
- `qr` — QR check-in: `npx @lumioui/cli add pro/scan-frame-qr`

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `shape?` | `ScanFrameShape` | Cutout proportions. Default "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. |
| `state?` | `ScanFrameState` | "scanning" breathes the line; "success" locks; "error" shakes. Default "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. |
| `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. |
| `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. |

Source: https://lumioui.com/components/scan-frame