Files
CV_Site_Nuxt/OKF_Nuxt/decisions/icons-via-nuxt-icon.md
T
Noel Sabia 24460083ff docs(okf): record the Nuxt Icon decision
- decisions/icons-via-nuxt-icon.md: local collection, mode svg,
  serverBundle collections empty, scanned client bundle; 3 icons, 1.23 kB
- linked from the bundle index and the decisions index, logged
2026-10-23 20:11:15 +02:00

3.3 KiB

type, title, description, tags, status, generated, verified, sources
type title description tags status generated verified sources
Decision Icons via Nuxt Icon Every icon comes from @nuxt/icon with the Material Symbols collection installed locally; the self-hosted icon webfont, its @font-face and its CSS class are gone.
decision
ui
icons
nuxt
payload
stable
by at
opencode-go/deepseek-v4.1-flash 2026-10-23T00:00:00Z
by at
human:noel 2026-10-23T00:00:00Z
id resource title
config nuxt.config.ts Icon module registration and options
id resource title
consumer app/components/AppBottomNav.vue First and only icon consumer so far
id resource title
package package.json @nuxt/icon and @iconify-json/material-symbols

Decision

Icons come exclusively from @nuxt/icon. The icon set is Material Symbols, installed as a local collection (@iconify-json/material-symbols), and names are written in full inside components:

<Icon name="material-symbols:badge" aria-hidden="true" class="text-[22px]" />

The previously self-hosted Material Symbols webfont is deleted: public/fonts/material-symbols-outlined-var.woff2, its @font-face in app/assets/css/main.css, and the .material-symbols-outlined class.

Why

  • One icon system. The nav rendered webfont glyphs by text content while everything else in the app is Tailwind utilities; a ligature typo silently produced a blank box.
  • Payload. The font was 3.9 MiB for three glyphs. The bundled icon data for the same three is 1.23 kB.
  • Self-hosting. The module's defaults are not local: mode: "css", provider server, iconifyApiEndpoint: https://api.iconify.design and fallbackToApi: true. Without an installed collection the site would call a third-party CDN at runtime, which is the same problem the self-hosted text fonts were chosen to avoid.

Configuration

Option Value Effect
mode 'svg' The icon is an inline <svg> in the SSR HTML, so it survives with JavaScript disabled. CSS mode would have fetched icon data on the client and painted after hydration.
serverBundle { collections: [] } 'auto' bundles every installed collection server-side; with only material-symbols installed that was an 8 MB icons.mjs. Empty means no server-side icon data at all.
clientBundle { scan: true } Bundles only the icons named in source. The build reports Nuxt Icon client bundle consist of 3 icons with 1.23KB(uncompressed) in size.

Consequences

  • Sizing is text-[…] on the <svg>: the component renders width="1em" height="1em", so font-size is the icon size.
  • Adding another Material Symbols icon is a code change only — the scanner picks the name up and the next build bundles it.
  • A different icon set means pnpm add @iconify-json/<set> plus new names; no other configuration changes.
  • Decorative icons carry aria-hidden="true", because every icon sits next to a text label.

Not verified

  • That the bars look right at 22px on a real phone — checked in the SSR HTML and the build output only.

Revisit when

  • A second icon set is wanted (two collections, two packages, no config change).
  • Many icons push the client bundle up: the alternative is mode: 'css', which ships class names and fetches icon data once instead of inline SVG per icon.