diff --git a/docs/elements/hole.mdx b/docs/elements/hole.mdx
index bf1f0ad..89e41dc 100644
--- a/docs/elements/hole.mdx
+++ b/docs/elements/hole.mdx
@@ -22,3 +22,218 @@ import CircuitPreview from "@site/src/components/CircuitPreview"
)`}
/>
+
+## Usage
+
+### Basic Circular Holes
+
+Circular holes are fully supported and commonly used for mounting:
+
+```tsx
+
+// or use x, y instead of pcbX, pcbY
+
+```
+
+You can also use `radius` instead of `diameter`:
+
+```tsx
+
+```
+
+### Mounting Holes Example
+
+```tsx
+
+ {/* Corner mounting holes */}
+
+
+
+
+
+```
+
+### Holes in Footprints
+
+```tsx
+
+
+
+
+
+ }
+/>
+```
+
+## Pill-Shaped (Oval) Holes
+
+The component props accept pill shape parameters, but the implementation currently only creates circular holes:
+
+```tsx
+// Props exist but not yet fully implemented
+
+```
+
+**Status**: The `getPcbSize()` method recognizes pill shapes, but `doInitialPcbPrimitiveRender()` only creates circular holes. This feature needs implementation to be fully functional.
+
+## Properties
+
+### HoleProps
+
+```typescript
+interface HoleProps {
+ name?: string
+
+ // For circular holes (currently supported)
+ diameter?: Distance // Diameter of the circular hole
+ radius?: Distance // Radius of the circular hole (alternative to diameter)
+
+ // For pill-shaped holes (props exist but not yet implemented)
+ shape?: "circle" | "pill" // Default is "circle"
+ width?: Distance // Width of the pill/oval hole
+ height?: Distance // Height of the pill/oval hole
+
+ // Position
+ pcbX?: number | string // X position on the PCB (or use x as alias)
+ pcbY?: number | string // Y position on the PCB (or use y as alias)
+ x?: number | string // Alternative to pcbX
+ y?: number | string // Alternative to pcbY
+}
+```
+
+:::info
+While the `shape`, `width`, and `height` props are accepted by the component, the implementation currently only creates circular holes regardless of the shape specified.
+:::
+
+## Circuit JSON Output
+
+### Circular Hole (Currently Supported)
+
+```json
+{
+ "type": "pcb_hole",
+ "pcb_hole_id": "pcb_hole_0",
+ "hole_shape": "circle",
+ "hole_diameter": 3,
+ "x": 5,
+ "y": 5
+}
+```
+
+### Pill-Shaped Hole (Specification Exists, Implementation Pending)
+
+The Circuit JSON specification supports pill-shaped holes:
+
+```json
+{
+ "type": "pcb_hole",
+ "pcb_hole_id": "pcb_hole_0",
+ "hole_shape": "oval",
+ "hole_width": 2,
+ "hole_height": 4,
+ "x": 0,
+ "y": 0
+}
+```
+
+However, the `` component does not yet generate this output. To implement pill-shaped holes, the `doInitialPcbPrimitiveRender()` method in `Hole.ts` needs to be updated to check for `props.shape === "pill"` and insert holes with `hole_shape: "oval"` instead of always creating circular holes.
+
+## Examples
+
+### Mounting Holes in a PCB
+
+```tsx
+
+ {/* Corner mounting holes */}
+
+
+
+
+
+```
+
+### In a Footprint
+
+```tsx
+
+ {/* Component mounting hole */}
+
+
+ {/* SMT pads */}
+
+
+
+ }
+/>
+```
+
+## Difference from PlatedHole
+
+The `` component creates **non-plated holes** (no copper pad or plating). If you need plated through-holes with copper pads, use the `` component instead.
+
+### Use `` for:
+- Mounting screw holes
+- Alignment pin holes
+- Mechanical clearance holes
+- Ventilation holes
+
+### Use `` for:
+- Through-hole component pins
+- Vias
+- Test points
+- Any hole that needs electrical connectivity
+
+## Rotation
+
+**Rotation is NOT supported** for basic `pcb_hole` at the Circuit JSON specification level. The `PcbHoleOval` and `PcbHoleCircleOrSquare` interfaces do not include rotation properties.
+
+- ❌ `` does NOT support rotation (even for pill shapes)
+- ✅ `` DOES support rotation via the `pcbRotation` prop
+
+For holes that need specific orientation:
+- Use `` for rotatable oval holes with pads
+- For basic holes, adjust component positioning or board design
+
+## Implementation Notes
+
+### What Needs to be Implemented for Pill Shape Support
+
+To fully support pill-shaped holes, the `doInitialPcbPrimitiveRender()` method in `lib/components/primitive-components/Hole.ts` needs to:
+
+1. Check if `props.shape === "pill"`
+2. If pill shape:
+ - Insert with `hole_shape: "oval"`
+ - Use `hole_width: props.width` and `hole_height: props.height`
+3. If circular (default):
+ - Continue using `hole_shape: "circle"` and `hole_diameter: props.diameter`
+
+Example implementation needed:
+
+```typescript
+const isPill = props.shape === "pill"
+
+if (isPill) {
+ const inserted_hole = db.pcb_hole.insert({
+ hole_shape: "oval",
+ hole_width: props.width,
+ hole_height: props.height,
+ x: position.x,
+ y: position.y,
+ // ... other properties
+ })
+} else {
+ // existing circular hole implementation
+}
+```
+
+## See Also
+
+- [PlatedHole Component](../footprints/platedhole) - For through-holes with copper pads
+- [Footprint Component](./footprint) - Using holes within footprints
+- [Board Component](./board) - PCB board configuration