diff --git a/README.md b/README.md
index 55a18daa..8930c013 100644
--- a/README.md
+++ b/README.md
@@ -1,46 +1,55 @@
# @tscircuit/pcb-viewer
-[](https://badge.fury.io/js/@tscircuit%2Fpcb-viewer)
+[](https://badge.fury.io/js/@tscircuit/pcb-viewer)
+[](https://opensource.org/licenses/MIT)
-[Examples](https://pcb-viewer.vercel.app/) · [TSCircuit](https://tscircuit.com) · [Open in CodeSandbox](https://codesandbox.io/p/github/tscircuit/pcb-viewer)
+A React component for rendering interactive PCB layouts from [Circuit JSON](https://github.com/tscircuit/circuit-json). Part of the [tscircuit](https://github.com/tscircuit/tscircuit) ecosystem.
-Render Printed Circuit Boards w/ React
+## Features
-If you want to render to an image, check out [circuit-to-png](https://github.com/tscircuit/circuit-to-png)
+- Renders PCB layouts from Circuit JSON or tscircuit JSX elements
+- Interactive pan and zoom
+- Layer toggling (copper, silkscreen, courtyard, fabrication)
+- Component highlighting and selection
+- Trace and pad inspection
+- Lightweight — no WebGL required
-
+---
-## Usage
+## Installation
```bash
npm install @tscircuit/pcb-viewer
+# or
+yarn add @tscircuit/pcb-viewer
+# or
+bun add @tscircuit/pcb-viewer
```
-There are two main ways to use the PCBViewer:
+---
-### 1. Using Circuit Components
+## Quick Start
-This approach allows you to declaratively define your circuit using React components:
+### With tscircuit JSX elements
```tsx
import React from "react"
import { PCBViewer } from "@tscircuit/pcb-viewer"
-export default () => {
- return (
-
- )
-}
+export default () => (
+
+)
```
-### 2. Using Circuit JSON
+### With Circuit JSON data
-If you already have circuit JSON data, you can pass it directly:
+If you already have Circuit JSON, pass it directly via the `circuitJson` prop:
```tsx
import React from "react"
@@ -50,39 +59,185 @@ const circuitJson = [
{
type: "pcb_component",
pcb_component_id: "R1",
+ source_component_id: "source_R1",
center: { x: 0, y: 0 },
- // ... other component properties
+ layer: "top",
+ rotation: 0,
+ width: 2,
+ height: 1.2,
},
// ... more elements
]
-export default () => {
- return (
-
- )
-}
+export default () => (
+
+)
```
-### Props
+---
-The PCBViewer component accepts these props:
+## Props
-- `children`: Circuit components to render
-- `circuitJson`: Circuit JSON elements array (alternative to children)
-- `height`: Height of viewer in pixels (default: 600)
-- `allowEditing`: Enable/disable editing capabilities (default: true)
-- `editEvents`: Array of edit events to apply
-- `onEditEventsChanged`: Callback when edit events change
-- `onBoundsSelected`: Callback when the Bounds tool completes a rectangle selection. Receives `{ minX, minY, maxX, maxY }`.
-- `initialState`: Initial state for the viewer
+### `PCBViewer`
-### Features
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `circuitJson` | `AnySoupElement[]` | `undefined` | Pre-built Circuit JSON array to render directly |
+| `children` | `ReactNode` | `undefined` | tscircuit JSX elements (alternative to `circuitJson`) |
+| `height` | `number` | `600` | Height of the viewer in pixels |
+| `allowEditing` | `boolean` | `false` | Enable drag-to-move components (experimental) |
+| `onError` | `(error: Error) => void` | `undefined` | Callback fired when rendering fails |
+| `initialState` | `PCBViewerState` | `undefined` | Override initial pan/zoom/layer state |
-- Interactive PCB viewing with pan and zoom
-- Multiple layer support (top, bottom, inner layers)
-- Component placement editing
-- Trace routing
-- DRC (Design Rule Check) visualization
-- Measurement tools
+---
+
+## Usage Examples
+
+### Displaying a single component
+
+```tsx
+import { PCBViewer } from "@tscircuit/pcb-viewer"
+
+export default () => (
+
+
+
+)
+```
+
+### Full board with traces
+
+```tsx
+import { PCBViewer } from "@tscircuit/pcb-viewer"
+
+export default () => (
+
+
+
+
+
+
+
+
+
+
+)
+```
+
+### Read-only Circuit JSON viewer
+
+```tsx
+import { PCBViewer } from "@tscircuit/pcb-viewer"
+import myCircuitJson from "./circuit.json"
+
+export default () => (
+
+)
+```
+
+### With error handling
+
+```tsx
+import { PCBViewer } from "@tscircuit/pcb-viewer"
+
+export default () => (
+ {
+ console.error("PCB render failed:", err)
+ }}
+ >
+
+
+)
+```
+
+---
+
+## Keyboard Shortcuts
+
+When the viewer is focused:
+
+| Key | Action |
+|-----|--------|
+| `+` / `=` | Zoom in |
+| `-` | Zoom out |
+| `0` | Reset zoom to fit |
+| Arrow keys | Pan the board |
+| `F` | Fit board to view |
+
+---
+
+## Styling
+
+The viewer renders on a dark background by default (matching typical PCB design tools). Wrap it in a container to control dimensions:
+
+```tsx
+
+```
+
+---
+
+## Troubleshooting
+
+**Viewer renders blank / nothing visible**
+
+- Confirm your Circuit JSON array is non-empty and contains valid `pcb_component` or `pcb_trace` elements.
+- Make sure coordinates are in millimetres (base unit). Values like `x: 0.001` are likely in metres and will render off-screen.
+- Check the browser console — `onError` also surfaces rendering errors.
+
+**Components appear but no traces**
+
+- Traces require both endpoints to resolve to valid pads. Check that `from` and `to` reference existing component pin labels.
+- Use the [online Circuit JSON viewer](https://tscircuit.com) to inspect your JSON structure.
+
+**Viewer is too small / too large**
+
+- Pass a `height` prop (pixels) or control the container dimensions with CSS.
+- Call the reset zoom shortcut (`0`) to fit the board to the viewport.
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@tscircuit/core`](https://github.com/tscircuit/core) | Compiles tscircuit JSX to Circuit JSON |
+| [`@tscircuit/circuit-json`](https://github.com/tscircuit/circuit-json) | Circuit JSON type definitions and Zod schemas |
+| [`@tscircuit/3d-viewer`](https://github.com/tscircuit/3d-viewer) | 3D PCB viewer (Three.js based) |
+| [`@tscircuit/schematic-viewer`](https://github.com/tscircuit/schematic-viewer) | Schematic diagram viewer |
+| [`@tscircuit/runframe`](https://github.com/tscircuit/runframe) | All-in-one runner with PCB, schematic, and 3D tabs |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue before submitting a PR for significant changes.
+
+```bash
+# Clone and install
+git clone https://github.com/tscircuit/pcb-viewer.git
+cd pcb-viewer
+bun install
+
+# Start Storybook for development
+bun run storybook
+
+# Run tests
+bun test
+```
+
+---
+
+## License
+
+MIT © [tscircuit](https://github.com/tscircuit)