From 442bfaa737d7dbc8e441ff0cd09f6bd12f4b47b6 Mon Sep 17 00:00:00 2001
From: ankan roy <ankan@Mac.lan>
Date: Thu, 12 Nov 2026 01:51:09 +0530
Subject: [PATCH] docs: document ordered trace path

---
 docs/elements/trace.mdx | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/elements/trace.mdx b/docs/elements/trace.mdx
index b48c01c6..537e4745 100644
--- a/docs/elements/trace.mdx
+++ b/docs/elements/trace.mdx
@@ -35,6 +35,7 @@ Here's a simple example connecting two components:
 | -------- | ----------- | ------- |
 | `from` | Starting point of the trace using a [port selector](../guides/tscircuit-essentials/port-and-net-selectors.md) | `".R1 > .pin1"` |
 | `to` | Ending point of the trace using a [port selector](../guides/tscircuit-essentials/port-and-net-selectors.md) | `".C1 > .pin1"` |
+| `path` | Ports to connect, in order. The trace is routed as a chain from the first port to the last. | `[".J1 > .pin1", ".U1 > .pin1"]` |
 | `name` | Names the trace and renders as the schematic net label for direct port-to-port traces (optional) | `"SENSE"` |
 | `maxLength` | Maximum length the trace can be (optional) | `"10mm"` |
 | `minLength` | Minimum length the trace must be (optional) | `"5mm"` |
@@ -91,6 +92,16 @@ Traces are automatically routed by tscircuit's [autorouting system](./board.mdx#
 
 You can customize the autorouting behavior by setting the `autorouter` property on the parent [`<board />`](./board.mdx) or [`<subcircuit />`](./subcircuit.mdx).
 
+## Ordered Paths
+
+Use `path` to connect ports in the given order, as a chain:
+
+```tsx
+<trace path={[".J1 > .pin1", ".ESD > .pin1", ".U1 > .pin1"]} />
+```
+
+Entries like `net.GND` are also allowed and attach the trace to a net. `path` specifies which ports to connect and their order; the router still draws the copper. Use `pcbPath` to specify manual copper geometry.
+
 ## Manual PCB Paths
 
 Sometimes you may want to manually specify the exact path a trace should take on the PCB. Provide a list of points with `pcbPath` to override autorouting and draw the route yourself. The coordinates are relative to a specific port defined by `pcbPathRelativeTo` (defaults to the `from` port). Entries in `pcbPath` can mix coordinate objects with [port selectors](../guides/tscircuit-essentials/port-and-net-selectors.md) so you can anchor the path to specific component pins.