diff --git a/docs/en/reference/default-theme-config.md b/docs/en/reference/default-theme-config.md
index 213fa347..33760375 100644
--- a/docs/en/reference/default-theme-config.md
+++ b/docs/en/reference/default-theme-config.md
@@ -280,10 +280,6 @@ interface SocialLink {
 }
 ```
 
-Icon styles are generated at build time from collections declared in your project's dependencies, and dev mode serves them from the dev server — no icon is ever fetched from an external service. Bare names are a `socialLinks` convenience and map to simple-icons; everywhere else icons are written as `collection:name`. Icons rendered only on the client (e.g. inside `<ClientOnly>`) can't be detected during the build; list them in [`icons.include`](site-config#icons) instead.
-
-To render one of these icons in your own Markdown or components, use the `VPIcon` component from `vitepress/theme` (`<VPIcon icon="lucide:rocket" />`), or the lower-level `useIcon` composable from `vitepress` when building a custom theme — both take fully qualified names.
-
 ## footer
 
 - Type: `Footer`
diff --git a/docs/en/reference/runtime-api.md b/docs/en/reference/runtime-api.md
index b69808ee..86d9a20b 100644
--- a/docs/en/reference/runtime-api.md
+++ b/docs/en/reference/runtime-api.md
@@ -136,6 +136,38 @@ router.onBeforeRouteChange = (to) => {
 
 For custom themes, the same router is available from [`enhanceApp`](../guide/custom-theme#theme-interface).
 
+## `useIcon` <Badge type="info" text="composable" />
+
+- **Type**: `(icon: MaybeRefOrGetter<string | { svg: string } | undefined>, el?: MaybeRefOrGetter<HTMLElement | null>) => ComputedRef<string | undefined>`
+
+Renders an [iconify](https://iconify.design/) icon through VitePress's icon pipeline. Takes a fully qualified `collection:name` (resolved against the `@iconify-json/*` packages in your project's dependencies) and returns the class to put on the element — `vpi-<collection>-<name>`.
+
+During SSR the name is registered on the page's [`SSGContext`](./site-config#postrender), so the build emits the icon's styles into the generated stylesheet; in dev, icons are served on demand by the dev server from the locally installed collections. No icon is ever fetched from an external service.
+
+```vue
+<script setup>
+import { useIcon } from 'vitepress'
+import { useTemplateRef } from 'vue'
+
+const el = useTemplateRef('el')
+const iconClass = useIcon('lucide:rocket', el)
+</script>
+
+<template>
+  <span ref="el" :class="iconClass" />
+</template>
+```
+
+Pass the template ref of the element carrying the class so dev mode can resolve the icon on it. The element needs the mask rules the default theme ships; in a custom theme without them, dev applies an inline equivalent and the generated stylesheet includes zero-specificity base rules for production.
+
+When using the default theme, the `VPIcon` component from `vitepress/theme` wraps this composable (and also accepts a raw `{ svg }` string):
+
+```vue-html
+<VPIcon icon="lucide:rocket" />
+```
+
+Icons rendered only on the client (e.g. inside `<ClientOnly />`) can't be collected during the build — list them in [`icons.include`](./site-config#icons) instead.
+
 ## `withBase` <Badge type="info" text="helper" />
 
 - **Type**: `(path: string) => string`
diff --git a/docs/en/reference/site-config.md b/docs/en/reference/site-config.md
index a04516bd..7f214127 100644
--- a/docs/en/reference/site-config.md
+++ b/docs/en/reference/site-config.md
@@ -493,7 +493,7 @@ Only production builds are affected. `vitepress preview` serves a root-absolute
 
 - Type: `{ include?: string[] }`
 
-Options for the generated icon styles. The build collects every iconify icon rendered during SSR ([social links](default-theme-config#sociallinks), the `VPIcon` theme component, or any element registered through the `useIcon` composable) and emits their styles as a hashed `assets/vp-icons.<hash>.css` asset. Names are fully qualified as `collection:name`, resolved against the `@iconify-json/*` packages declared in your project's dependencies (`socialLinks` is the one place bare names are accepted — they map to [simple-icons](https://simpleicons.org/), which VitePress itself depends on).
+Options for the generated icon styles. The build collects every iconify icon rendered during SSR. Names are fully qualified as `collection:name`, resolved against the `@iconify-json/*` packages declared in your project's dependencies.
 
 Icons rendered only on the client — inside `<ClientOnly>`, or after hydration — are invisible to SSR collection. List them in `include` to force them into the stylesheet:
 
@@ -674,14 +674,11 @@ export default {
 interface SSGContext {
   content: string
   teleports?: Record<string, string>
-  /** icons rendered on the page, emitted into the generated stylesheet */
   vpIcons: Set<string>
   [key: string]: any
 }
 ```
 
-Custom themes can add qualified `collection:name` icon names to `vpIcons` during SSR to have their styles emitted — the `useIcon` composable from `vitepress` does this for you.
-
 ### transformHead
 
 - Type: `(context: TransformContext) => Awaitable<HeadConfig[]>`
@@ -756,7 +753,9 @@ For simpler cases, it may be possible to use the [`head`](./frontmatter-config#h
 Don't mutate anything inside the `context`. Also, modifying the html content may cause hydration problems in runtime.
 :::
 
+::: note
 The icon stylesheet link still carries its `vp-icons.__VP_ICONS_HASH__.css` placeholder at this point — the content hash only exists once every page has rendered, and it is substituted right after. Hooks that inline or fingerprint head assets should skip that tag.
+:::
 
 ```ts
 export default {