diff --git a/docs/components/icon.md b/docs/components/icon.md
index daf45d988..f8d3d9895 100644
--- a/docs/components/icon.md
+++ b/docs/components/icon.md
@@ -4,7 +4,9 @@
Icons are symbols that can be used to represent or provide context to various options and actions within an application.
-Shoelace comes bundled with over 1,100 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. Click or tap on an icon below to copy the name and use it like this.
+Shoelace comes bundled with over 1,100 icons courtesy of the [Bootstrap Icons](https://icons.getbootstrap.com/) project. If you need more, you can also [register a custom library](#registering-custom-libraries).
+
+Click or tap on an icon below to copy the name and use it like this.
```html
@@ -54,12 +56,152 @@ Icons are sized relative to the current font size. To change their size, set the
### Custom Icons
-Custom icons can be loaded by setting the `src` attribute. Only SVG images are supported
+Custom icons can be loaded by setting the `src` attribute. Only SVG images are supported.
```html preview
```
+## Registering Custom Libraries
+
+You can register custom icon libraries by calling the `registerLibrary()` method on any `` element. An icon library can exist locally or on a CORS-enabled CDN, and there is no limit to how many you can register. There is no cost associated with registering multiple libraries, as individual icons are only requested when they're used.
+
+The `registerLibrary()` method accepts three arguments: the name of the library, a function that resolves an icon name to an SVG URL, and an optional function that can be used to mutate the SVG element. Once registered, icons can be displayed by setting the icon's `library` prop as shown below.
+
+### Local Registration
+
+This example registers a custom icon library named `my-icons` that serves icons from a local `/public/icons` directory. Additional examples can be found below for some popular open source icon libraries.
+
+```html
+
+
+
+```
+
+?> Calling `registerLibrary()` will register the library for all icons. You don't need to call it more than once for the same library!
+
+### Feather Icons
+
+This example registers and displays a handful of icons from the [Feather Icons](https://feathericons.com/) library using the jsDelivr CDN.
+
+```html preview
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### Heroicons
+
+The following example registers the Heroicons library using the jsDelivr CDN.
+
+```html preview
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+
+### Ionicons
+
+The following example registers the Ionicons library using the jsDelivr CDN.
+
+```html preview
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### Unicons
+
+The following example registers the Unicons library using the jsDelivr CDN.
+
+```html preview
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+