diff --git a/docs/elements/trace.mdx b/docs/elements/trace.mdx
index 788d291..a95719d 100644
--- a/docs/elements/trace.mdx
+++ b/docs/elements/trace.mdx
@@ -1,6 +1,5 @@
 ---
 title: <trace />
-sidebar_position: 5
 description: >-
   The `<trace />` element represents an electrical connection between two or
   more points in your circuit. Traces can connect components, nets, or specific
@@ -36,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"` |
+| `schDisplayLabel` | Schematic label text to render for the trace instead of an autogenerated fallback net label (optional) | `"SENSE"` |
 | `maxLength` | Maximum length the trace can be (optional) | `"10mm"` |
 | `minLength` | Minimum length the trace must be (optional) | `"5mm"` |
 | `width` | Width of the trace (optional) | `"0.2mm"` |
@@ -57,6 +57,30 @@ Traces can connect to named nets like power and ground:
   )
 `} />
 
+## Custom Schematic Labels
+
+Use `schDisplayLabel` when you want a trace to show a specific net label in the schematic. This is useful for direct port-to-port traces, where the renderer would otherwise fall back to an autogenerated label based on the connected ports.
+
+<CircuitPreview defaultView="schematic" hidePCBTab hide3DTab code={`
+  export default () => (
+    <board width="10mm" height="10mm">
+      <resistor name="R1" resistance="10k" footprint="0402" schX={-2} />
+      <chip name="U1" footprint="soic8" schX={2} />
+      <trace
+        from=".R1 > .pin1"
+        to=".U1 > .pin1"
+        schDisplayLabel="SENSE"
+      />
+      <trace
+        from=".R1 > .pin2"
+        to="net.GND"
+      />
+    </board>
+  )
+`} />
+
+`schDisplayLabel` controls the schematic label that is drawn for the trace; it does not rename the underlying net.
+
 ## Autorouting
 
 Traces are automatically routed by tscircuit's [autorouting system](./board.mdx#setting-the-autorouter). The autorouter will: