diff --git a/docs/packages/player.mdx b/docs/packages/player.mdx
index 65197803a3..88155ca7ec 100644
--- a/docs/packages/player.mdx
+++ b/docs/packages/player.mdx
@@ -141,6 +141,41 @@ player.addEventListener("timeupdate", (event) => {
| `error` | `{ message }` | Load or runtime error; a video adds its `MediaError` `code` |
| `playbackerror` | `{ source, error }` | The browser blocked playback, for example unmuted autoplay |
+## Custom icons and loading mark
+
+Put an element with a `slot` attribute inside the player to replace a control glyph or the loading mark. Anything you leave out keeps the default.
+
+| Slot | Shown when | Default size |
+| ------------------- | ----------------------------------------------------------- | ------------ |
+| `play-icon` | Paused | 24 px |
+| `pause-icon` | Playing | 24 px |
+| `volume-high-icon` | Unmuted, volume 0.5 or higher | 20 px |
+| `volume-low-icon` | Unmuted, volume below 0.5 | 20 px |
+| `volume-muted-icon` | Muted | 20 px |
+| `loading-mark` | Preparing shader transitions, loading assets, and buffering | 78 px |
+
+```html title="index.html"
+
+
+
+
+
+```
+
+Glyphs take the control bar's color through `currentColor`, and you set their size. Put `slot` on the `