diff --git a/docs/elements/spicemodel.mdx b/docs/elements/spicemodel.mdx
new file mode 100644
index 0000000..061b9a5
--- /dev/null
+++ b/docs/elements/spicemodel.mdx
@@ -0,0 +1,117 @@
+---
+title:
+description: Attach a custom SPICE subcircuit model to a tscircuit component.
+---
+
+## Overview
+
+`` attaches a SPICE `.subckt` model to a source component for
+analog simulation. Use it when a component needs behavior that is not covered by
+the built-in SPICE output, such as a vendor model, an op-amp macro-model, or a
+custom diode model.
+
+The model is usually passed through the parent component's `spiceModel` prop.
+During simulation, tscircuit maps the `.subckt` pins to the parent component's
+ports and emits a subcircuit instance into the generated SPICE netlist.
+
+import CircuitPreview from "@site/src/components/CircuitPreview"
+
+ (
+
+
+ }
+ />
+
+
+
+
+
+
+
+
+
+
+)
+`}
+/>
+
+## Properties
+
+| Property | Description | Example |
+| --- | --- | --- |
+| `source` | SPICE source text containing a `.subckt` declaration. | `` `.subckt LM358 1 2 3 4 5 ...` `` |
+| `spicePinMapping` | Optional map from `.subckt` pin names to parent component port names. Use this when the SPICE model pins do not match the tscircuit port names. | `{{ "1": "pin1", "2": "pin2" }}` |
+
+## Pin Mapping
+
+If a `.subckt` pin name matches a parent component port name, no mapping is
+needed. In the diode example above, `ANODE` and `CATHODE` match the chip's
+`pinLabels`.
+
+Use `spicePinMapping` when the model uses different pin names or numeric pins:
+
+```tsx
+const lm358Model = `
+.subckt LM358 1 2 3 4 5
+RIN 2 3 10Meg
+.ends LM358
+`
+
+export default () => (
+
+
+ }
+ />
+
+)
+```
+
+Every `.subckt` pin must resolve to exactly one parent port. If a mapped SPICE
+pin is not present in the `.subckt`, or if a pin cannot be resolved to a port,
+tscircuit reports a `source_invalid_component_property_error` for `spiceModel`.