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.

the design on your app, in 84 seconds

1:24 · sound on

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:

<View testID="image-target:LoginCard">
  <Text>Welcome back</Text>
  <TextInput placeholder="Email" />
  <Button title="Sign In" onPress={() => {}} />
</View>

<View testID="image-target:LoginCard">
  <Text>Welcome back</Text>
  <TextInput placeholder="Email" />
  <Button title="Sign In" onPress={() => {}} />
</View>

The text after image-target: becomes the label shown in the target list. Add as many targets as you like throughout your app:

// Header section
<View testID="image-target:Header">
  <Logo />
  <NavBar />
</View>

// Product card
<View testID="image-target:ProductCard">
  <Image source={product.image} />
  <Text>{product.name}</Text>
  <Text>{product.price}</Text>
</View>

// Bottom tab bar
<View testID="image-target:TabBar">
  <TabButton icon="home" />
  <TabButton icon="search" />
  <TabButton icon="profile" />
</View>

// Header section
<View testID="image-target:Header">
  <Logo />
  <NavBar />
</View>

// Product card
<View testID="image-target:ProductCard">
  <Image source={product.image} />
  <Text>{product.name}</Text>
  <Text>{product.price}</Text>
</View>

// Bottom tab bar
<View testID="image-target:TabBar">
  <TabButton icon="home" />
  <TabButton icon="search" />
  <TabButton icon="profile" />
</View>

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 — See exactly why components re-render
• Environment Inspector — View and search environment variables
• Network Monitor — 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 for registration, dependencies, and browser boundaries.

Native iOS (Swift)

Image Overlay is also part of Buoy for Swift for SwiftUI and UIKit apps. Setup and what the Swift version covers are in the Swift tools guide.