# Scan viewfinder

> An overlay for a camera preview: brackets drift while searching, snap onto the subject with a cue, then a scan line sweeps while short findings fly out. It draws the overlay only; camera and detection are yours.

- Type: Component (feedback)
- Access: Free, open source (MIT)
- Page: https://goodui.dev/native/components/scan-viewfinder
- Markdown: https://goodui.dev/native/components/scan-viewfinder.md
- Registry item: https://goodui.dev/native/r/scan-viewfinder.json
- Dependencies: react-native-reanimated
- Keywords: react native camera overlay, scanner viewfinder, ai food scanner, object detection overlay, scan animation

## When to use

- Apps that photograph something to analyse it: food, plants, documents, coins.
- Giving feedback while an on-device detector looks for a subject.

## When not to use

- QR and barcode scanning: use the camera module's scanner with a plain frame.
- Plain photo capture: a shutter is enough.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add https://goodui.dev/native/r/scan-viewfinder.json
npx expo install --fix
```

The component lands in `components/goodui-native/scan-viewfinder/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs locale.

Built-in strings follow `<GooduiLocaleProvider>` (one [language pack](https://goodui.dev/native/r/locale-tr.json) translates the whole kit); the `labels` prop overrides them for one instance.

## Usage

```tsx
import { CameraView } from "expo-camera";
import { ScanViewfinder, type ScanState } from "@/components/goodui-native/scan-viewfinder/scan-viewfinder";

const TARGET = { x: 0.15, y: 0.25, width: 0.7, height: 0.45 };

<ScanViewfinder state={state} target={TARGET} chips={["Salmon", "Rice"]}>
  <CameraView style={{ flex: 1 }} />
</ScanViewfinder>
```

## API reference

### ScanViewfinder

`import { ScanViewfinder } from "@/components/goodui-native/scan-viewfinder/scan-viewfinder";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `"done" \| "searching" \| "locked" \| "analysing"` | – | searching drifts the brackets, locked snaps them to `target`, analysing runs the scan line and chips. |
| `target` | `{ x: number; y: number; width: number; height: number }` | `DEFAULT_TARGET` | The subject, as fractions of the frame. |
| `chips` | `string[]` | `[]` | Short facts that fly out of the subject while analysing: "Salmon", "Rice". |
| `children` (required) | `ReactNode` | – | The camera preview. |
| `labels` | `Partial<ScanViewfinderLabels>` | – | – |
| `style` | `StyleProp<ViewStyle>` | – | Style for the outer container. |
| `testID` | `string` | – | Identifier for end-to-end tests. |

## Accessibility

- The status line is a polite live region, so state changes are announced.
- Brackets, the scan line and chips are hidden from screen readers. Say the result on the next screen.

## Motion

- Brackets drift on looping sine timings, then spring onto the target.
- On lock, the frame flashes and the brackets take the accent color.
- While analysing, a scan line loops and chips burst out in a staggered ring.
- Reduced motion: no drift or sweep. Chips fade in at their final place.

## Haptics

- drop on lock, a tick for each chip.

## Performance

- Brackets and the scan line run on the UI thread, over the camera preview.

## Notes for AI

- It fills its parent with flex: 1, so the parent needs a height.
- `target` is in fractions of the frame, measured from the top left.
- State does not advance on its own: move through searching, locked, analysing and done yourself.
- `chips` are short facts from a real result, cut off at about 130 pt. Do not show invented findings as if they were detected.
- It stays left to right under RTL because it is measured from the physical camera frame.

## Related

- [Generation queue](https://goodui.dev/native/components/generation-queue.md): Cards for long AI jobs: each one shows its status, a fill and a light sweep while running, a rolling percentage, and cancel, retry and open actions.
- [Blur reveal](https://goodui.dev/native/components/blur-reveal.md): Shows a result arriving: a scan line wipes down a blurred picture and leaves it sharp, then the frame settles with a spring and an unlock cue.
- [AI provider](https://goodui.dev/native/components/ai-provider.md): The logic layer behind the AI components, with no UI: a typed provider adapter with an offline mock, a credit ledger that keeps subscription and bought credits apart, and a generation queue that charges, refunds and retries.

## Guidance for AI tools

Scan viewfinder: An overlay for a camera preview: brackets drift while searching, snap onto the subject with a cue, then a scan line sweeps while short findings fly out. It draws the overlay only; camera and detection are yours. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt