# Image Overlay
Overlay design mockups directly on your running app to compare against your implementation. Load a mockup, match its scale and position to the screen, and adjust opacity to compare spacing and alignment.
The demo shows component targeting and alignment on a mock storefront.
## Installation
That's it. Image Overlay appears in your FloatingDevTools menu.
---
## Marking Components as Targets
To make a component discoverable in **Component Mode**, add a `testID` with the `image-target:` prefix:
```tsx
Welcome back
```
The text after `image-target:` becomes the label shown in the target list. Add as many targets as you like throughout your app:
```tsx
// Header section
// Product card
{product.name}{product.price}
// Bottom tab bar
```
> **Only `image-target:` testIDs are scanned** — your existing `testID` props for testing (e.g., `testID="login-button"`) are not affected and won't appear in the target list.
---
## Loading Images
You can load a design mockup in two ways:
- **Paste from Clipboard** — Copy an image in Figma (or anywhere) and tap "Paste from Clipboard". Requires `expo-clipboard`.
- **Enter a URL** — Paste a direct image URL and tap "Load". Works with any React Native setup.
Clipboard image loading requires `expo-clipboard` and its native setup. Use a direct image URL for the minimal path; load it, reduce opacity, align the mockup, and lock the overlay before interacting with the screen.
---
## Two Modes
### Component Mode
Tap **Component Match** to scan your app and see all tagged targets. Select one, and the overlay pins to that component, measuring its exact position and size. Turn on **Auto Track** and the overlay follows the component when it scrolls or moves.
### Free Mode
Manually position and resize the overlay anywhere on screen. Drag to move, pinch to scale — useful when you want to compare a full-screen mockup or a section that doesn't map to a single component.
---
## What You Can Do
- **Opacity control** — Blend the mockup over your live UI to spot differences
- **Scale & zoom** — Resize the overlay to match your layout
- **X/Y offset** — Fine-tune positioning for exact alignment
- **Flip** — Mirror the overlay horizontally or vertically
- **Lock** — Prevent accidental repositioning while comparing
- **Outline toggle** — Show overlay boundaries for precise placement
- **Auto-track** — Remeasures the target component every frame, so the overlay stays on it while the screen scrolls, animates or shifts
---
## What's Next
- [Highlight Updates](./highlight-updates) — See exactly why components re-render
- [Environment Inspector](./env) — View and search environment variables
- [Network Monitor](./network) — Inspect supported HTTP requests
---
## FAQ
### How do I compare my React Native UI against a Figma design?
Export the frame as an image, then load it in Image Overlay from clipboard or URL — adjust opacity over the running app and differences jump out.
## Swift MCP controls
The Swift iOS port exposes an `image-overlay` adapter. Check the selected device's capabilities before calling it; these actions are not registered by the React Native tool.
Use `listTargets` and `selectTarget({ id })` to attach an overlay to a marked app view. `loadImage({ url })` starts an HTTP(S) image download. Read `getSnapshot` until `loading` is false, then check `hasImage` and `error`. Image loading shares the on-device controller and excludes its requests from Buoy Network capture.
`setSettings` accepts opacity (0–1), positive scale, point offsets (`offsetX`, `offsetY`), and boolean visibility, lock, flip, outline, and tracking settings (`visible`, `locked`, `flipped`, `flippedY`, `showOutline`, `autoTrack`). `fitToScreen` fits the image to the screen width. `resetSettings` resets placement adjustments, opacity, and flips. `remove` clears the image and cancels pending loading.
## Web support
Tag browser targets with data-testid="image-target:Name" and import the browser registration before React DOM. The shared controls support target and free placement. Import it from the package's `/web` entry (7.0.41 or later). See [Web installation](../web/installation#tool-setup) for registration, dependencies, and browser boundaries.
## Native iOS (Swift)
Image Overlay is also part of [Buoy for Swift](../swift/overview) for SwiftUI and UIKit apps. Setup and what the Swift version covers are in the [Swift tools guide](../swift/tools#image-overlay).