docs: explain better icon examples of custom aliases on icon fonts (#21955)

Co-authored-by: Andrew Henry <[email protected]>
Resolves #21784

Author: antonhansson0624

packages/docs/src/examples/v-btn/prop-icon.vue

@@ -6,7 +6,7 @@
       </v-col>
 
       <v-col cols="auto">
-        <v-btn density="comfortable" icon="$vuetify"></v-btn>
+        <v-btn density="comfortable" icon="mdi-cow"></v-btn>
       </v-col>
 
       <v-col cols="auto">
@@ -24,7 +24,7 @@
       </v-col>
 
       <v-col cols="auto">
-        <v-btn icon="$vuetify"></v-btn>
+        <v-btn icon="mdi-cow"></v-btn>
       </v-col>
 
       <v-col cols="auto">

packages/docs/src/pages/en/features/icon-fonts.md

@@ -439,12 +439,64 @@ app.mount('#app')
 </template>
 ```
 
-## Built-in aliases
+## Icon aliases
 
-The following icons are available as aliases for use in Vuetify components:
+Icon aliases allow you to define short, reusable names for icons that can map to different sources — such as icon names from a set, local Vue components, or raw SVG paths. Aliases are referenced with an initial `$` followed by the name of the alias, e.g. `$product`. The following icons are available as aliases for use in Vuetify components:
 
 <DocIconTable />
 
+### Custom aliases
+
+If you are developing custom Vuetify components, you can extend the `aliases` object to utilize the same functionality that internal Vuetify components use. This makes it easier to manage icons consistently throughout your project.
+
+Here’s an example:
+
+```js { resource="src/plugins/vuetify.js" }
+import { createVuetify } from 'vuetify'
+import AccountIcon from './account-icon.vue'
+import ClosetIcon from './closet-icon.vue'
+
+export const customIcons = {
+  mdiCustomAlias: 'mdi-cow',
+  account: AccountIcon,
+  annotation: [
+    'M14 9.45h-1v-1a1 1 0 0 0-2 0v1h-1a1 1 0 0 0 0 2h1v1a1 1 0 0 0 2 0v-1h1a1 1 0 0 0 0-2Zm6.46.18A8.5 8.5 0 1 0 6 16.46l5.3 5.31a1 1 0 0 0 1.42 0L18 16.46a8.46 8.46 0 0 0 2.46-6.83Zm-3.86 5.42l-4.6 4.6l-4.6-4.6a6.49 6.49 0 0 1-1.87-5.22A6.57 6.57 0 0 1 8.42 5a6.47 6.47 0 0 1 7.16 0a6.57 6.57 0 0 1 2.89 4.81a6.49 6.49 0 0 1-1.87 5.24Z',
+  ],
+  closet: ClosetIcon,
+}
+
+export const vuetify = createVuetify({
+  theme: {
+    defaultTheme: 'light',
+    //
+  },
+  icons: {
+    defaultSet: 'mdi',
+    aliases: {
+      ...customIcons,
+    },
+  },
+})
+```
+
+```html
+<template>
+  <v-btn prepend-icon="$account">Custom Icon 1</v-btn>
+  <v-btn prepend-icon="$mdiCustomAlias">Custom Icon 2</v-btn>
+  <v-btn prepend-icon="$closet">Custom Icon 3</v-btn>
+  <v-btn prepend-icon="$annotation">Custom Icon 4</v-btn>
+  <v-btn prepend-icon="mdi-close">Default MDI Icon</v-btn>
+</template>
+```
+
+In this setup:
+
+* $account and $closet render your own Vue component SVG icons.
+* $mdiCustomAlias references an alias for the mdi-cow icon.
+* $annotation references inline SVG path data.
+
+This approach gives you flexibility: you can mix external libraries with your own icons seamlessly, while keeping your templates cleaner and easier to maintain.
+
 ## Multiple icon sets
 
 Out of the box, Vuetify supports the use of multiple *different* icon sets at the same time. The following example demonstrates how to change the default icon font to Font Awesome (`fa`) while still maintaining access to the original Material Design Icons (`mdi`) through the use of a prefix:
@@ -550,29 +602,3 @@ export default createVuetify({
   },
 })
 ```
-
-## Extending available aliases
-
-If you are developing custom Vuetify components, you can extend the `aliases` object to utilize the same functionality that internal Vuetify components use. Icon aliases are referenced with an initial `$` followed by the name of the alias, e.g. `$product`.
-
-```js { resource="src/plugins/vuetify.js" }
-import { createVuetify } from 'vuetify'
-import { aliases, mdi } from 'vuetify/iconsets/mdi'
-
-export default createVuetify({
-  icons: {
-    aliases: {
-      ...aliases,
-      product: 'mdi-dropbox',
-      support: 'mdi-lifebuoy',
-    },
-  },
-})
-```
-
-```html
-<template>
-  <v-icon icon="$product" />
-  <v-icon icon="$support" />
-</template>
-```