# Debug Borders

<!-- ::platform-badge platform="both" -->

Inspect layout boundaries on the running app. Debug Borders draws colored borders and labels over your running app, then lets you tap any label to inspect the component underneath — its `testID`, styles, position, and accessibility info — without leaving the device.

---

On web, borders also show on plain DOM nodes. They do not show objects inside the 3D scene.

## Installation

<!-- ::PM npm="npm install @buoy-gg/debug-borders" yarn="yarn add @buoy-gg/debug-borders" pnpm="pnpm add @buoy-gg/debug-borders" bun="bun add @buoy-gg/debug-borders" -->

That's it. Debug Borders appears in your FloatingDevTools menu.

---

## Three Modes, One Tap

Tap the BORDERS icon in the floating menu to cycle through modes:

| Mode        | What you see                                                                 |
| ----------- | ---------------------------------------------------------------------------- |
| **Off**     | No border overlay                                                       |
| **Borders** | Rainbow-colored borders on every component, colored by depth in the tree      |
| **Labels**  | Borders + labels, but only for components with a `testID` or `accessibilityLabel` |

Borders are touch-through — they never interfere with interacting with your app — and they track layout changes automatically.

---

## Labels Mode

Labels mode filters the noise down to components you've actually identified:

- **Color-coded by identifier** — green for `testID`, pink for `accessibilityLabel`
- **Labels sit above their boxes** so they don't obscure content, and overlapping labels stack upward automatically
- **Hidden screens stay clean** — borders auto-hide on inactive screens in stack navigators, and whenever a DevTools modal is open

---

## Tap to Inspect

Tap any label to open a full inspection modal for that component:

- **Identifiers** — `testID`, `accessibilityLabel`, `nativeID`, and `key`
- **Component info** — the React component that rendered it, its parent, display name, and native view type
- **Position & size** — x/y coordinates, width, height, and depth in the tree
- **Accessibility** — role, hint, and state
- **Styles** — the full computed styles in an interactive viewer

Use it to answer "what testID does QA need for this button?" or "which component owns this padding?" straight from the device.

---

## Customization

Want your own naming or colors? Build the tool with `createDebugBordersTool`:

```tsx
import { createDebugBordersTool } from "@buoy-gg/debug-borders";

const layoutTool = createDebugBordersTool({
  name: "LAYOUT",
  description: "Layout visualizer",
  offColor: "#9ca3af",
  bordersColor: "#ec4899",
  labelsColor: "#8b5cf6",
  id: "debug-borders",
});
```

Pass it to `FloatingDevTools` via the `apps` array and it replaces the default preset.

---

## What's Next

- [Highlight Updates](./highlight-updates) — See why your components re-render
- [Image Overlay](./image-overlay) — Overlay design mockups on your running app
- [Bench](./perf-monitor) — Benchmark FPS, CPU, and memory on a real device

---

## FAQ

### How do I see React Native layout boundaries on a device?

Install `@buoy-gg/debug-borders` and tap the BORDERS icon to cycle modes — Borders draws depth-colored outlines on every component, and Labels narrows that to components with a `testID` or `accessibilityLabel`. The overlays are touch-through, so your app stays usable.

### Can I inspect a component's styles without a desktop debugger?

Yes — tap any label to inspect the component underneath on the device itself: its `testID`, styles, position, and accessibility info. Nothing has to be attached to your machine.

## Web support

Import @buoy-gg/core/web/register before React DOM. The `buoy()` Vite plugin adds it for you. The shared overlay measures DOM elements and draws their borders and labels. 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.