From f92b7dd7ed24769a71236e97b3836b4f24092f0c Mon Sep 17 00:00:00 2001
From: Simeon Simeonoff <sim.simeonoff@gmail.com>
Date: Thu, 18 Jul 2024 19:06:46 +0300
Subject: [PATCH 1/2] refactor(icon): add icon references section

---
 doc/en/components/layouts/icon.md | 49 +++++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)

diff --git a/doc/en/components/layouts/icon.md b/doc/en/components/layouts/icon.md
index fdb24df5b..91f317506 100644
--- a/doc/en/components/layouts/icon.md
+++ b/doc/en/components/layouts/icon.md
@@ -205,7 +205,52 @@ public iconRef(icon: IgrIcon) {
 }
 ```
 
-Then you'd use it in the same way as described in the component sample above.
+### Icon References
+
+In the previous section we explored icon registration via either `registerIcon` or `registerIconFromText`. We can also create icon aliases that refer to already registered icons. This allows us to refer to the aliased icon in our template, giving us the freedom to swap icons by simply changing the underlying reference in our business logic, without modifying the markup.
+
+Let's say we have a couple of icons in our application that represent state - a play icon and a pause icon. We want to swap the play icon with the pause icon when something is playing and vice-versa.
+
+The traditional approach is to write some business logic in our template that does the swapping. By aliasing the icon, we can simply change the underlying reference so when the content is playing we swap the reference with the pause icon and vice-versa. To do this, we can use the `setIconRef` function.
+
+Enough talking, here's a practical example of how to achieve all of the above:
+
+<!-- WebComponents -->
+```ts
+import {
+  registerIcon,
+  registerIconFromText,
+  setIconRef,
+} from "igniteui-webcomponents";
+
+// Let's register the play and pause icons first
+registerIcon(
+  "play",
+  "https://cdn.jsdelivr.net/npm/material-design-icons@3.0.1/av/svg/production/ic_play_circle_filled_24px.svg",
+  "material"
+);
+
+registerIcon(
+  "pause",
+  "https://cdn.jsdelivr.net/npm/material-design-icons@3.0.1/av/svg/production/ic_pause_circle_filled_24px.svg",
+  "material"
+);
+
+const playing = false;
+
+// Let's create an alias for the player control icon
+setIconRef("control", "player", {
+    name: this.playing ? "pause" : "play",
+    collection: "material"
+});
+```
+
+```html
+<igc-icon name="control" collection="player"></igc-icon>
+```
+<!-- end: WebComponents -->
+
+`sample="/layouts/icon/reference", height="70", alt="{Platform} Icon References"`
 
 ### Size
 
@@ -265,4 +310,4 @@ igc-icon {
 ## Additional Resources
 
 * [{ProductName} **Forums**]({ForumsLink})
-* [{ProductName} **GitHub**]({GithubLink})
\ No newline at end of file
+* [{ProductName} **GitHub**]({GithubLink})

From a26d4af31682feca4f8efafdf2ab8388236b3bfb Mon Sep 17 00:00:00 2001
From: Simeon Simeonoff <sim.simeonoff@gmail.com>
Date: Thu, 18 Jul 2024 19:17:34 +0300
Subject: [PATCH 2/2] refactor(icon): fix sample link

---
 doc/en/components/layouts/icon.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/en/components/layouts/icon.md b/doc/en/components/layouts/icon.md
index 91f317506..cb726bf3a 100644
--- a/doc/en/components/layouts/icon.md
+++ b/doc/en/components/layouts/icon.md
@@ -250,7 +250,7 @@ setIconRef("control", "player", {
 ```
 <!-- end: WebComponents -->
 
-`sample="/layouts/icon/reference", height="70", alt="{Platform} Icon References"`
+`sample="/layouts/icon/references", height="70", alt="{Platform} Icon References"`
 
 ### Size