SVG mode: ids inside icons come from a global counter, so the same page renders different HTML on every request

Open Beginner friendly
#585 1 comment 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
77/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
nuxt, typescript
Domain
frontend

Research direction

Read src/runtime/components/svg.ts and inspect how NuxtIconSvg passes props to Iconify's Icon; the issue identifies the missing stable id prop and suggests Vue's useId(). Check existing tests around SVG rendering and the earlier useId() fixes in commits f5e74f5, then verify repeated server renders produce the same SVG ids and that server and client ids stay consistent.

Written by the indexing model from the issue text.

Description

Environment
  • @nuxt/icon: 2.2.1
  • @iconify/vue: 5.0.0
  • Nuxt: 4.6.4
  • icon.mode: 'svg'
Reproduction

StackBlitz: https://stackblitz.com/edit/github-komwydjq-7hp6bfpa

Note: the StackBlitz starter currently locks @nuxt/cli 4.0.1, whose dev server crashes in StackBlitz with options.hostname.toLowerCase is not a function. The reproduction therefore overrides @nuxt/cli to 4.0.3 (pnpm.overrides) and pins nuxt to 4.6.4. Nothing else in package.json changed.

Based on the Nuxt v4 starter with @nuxt/icon added. One custom icon whose SVG contains an id (a gradient):

<!-- app/assets/icons/gradient.svg -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><defs><linearGradient id="fill"><stop offset="0" stop-color="red"/><stop offset="1" stop-color="blue"/></linearGradient></defs><circle cx="12" cy="12" r="10" fill="url(#fill)"/></svg>
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/icon'],
  icon: {
    mode: 'svg',
    customCollections: [{ prefix: 'custom', dir: './app/assets/icons' }],
  },
})
<!-- app/app.vue -->
<script setup lang="ts">
// Reads the id the server rendered into the icon (hydration keeps the server markup).
const renderedId = ref('')
onMounted(() => {
  renderedId.value = document.querySelector('linearGradient')?.id ?? ''
})
</script>

<template>
  <Icon name="custom:gradient" size="64" />
  <p>Gradient id rendered by the server: <strong>{{ renderedId }}</strong></p>
</template>

Reload the page a few times. The id counts up with every request, so the same page renders different HTML each time:

iconifyVue1, iconifyVue2, iconifyVue3, iconifyVue4, iconifyVue5   (5 reloads, nuxt dev)
iconifyVue0, iconifyVue1, iconifyVue2, iconifyVue3, iconifyVue4   (5 requests, production build)
Describe the bug

NuxtIconSvg renders Iconify's <Icon> without an id prop. Without it, Iconify's replaceIDs() prefixes ids with iconifyVue plus a module-level counter that keeps counting across all requests the server handles. Each render of the same page therefore produces different ids, and different HTML.

Iconify already has a solution for this. With an id prop it uses id + 'ID' + localCounter (per component instance), as noted in @iconify/vue: "Counter for ids based on 'id' property to render icons consistently on server and client".

Why it matters
  • ISR / caching: Vercel only skips an ISR write when a revalidation produces identical output (ISR limits and pricing). With changing ids, every revalidation of an unchanged page is billed as a new write. The same goes for anything that compares or hashes the HTML (ETags, diffing).
  • Server/client consistency: the ids rendered on the server depend on how many requests the instance has served before, so they can't match what the client would generate.
Suggested fix

Pass a stable id to Iconify in NuxtIconSvg, e.g. Vue's useId():

// src/runtime/components/svg.ts
const id = useId()
// …
return () => h(Iconify, {
  icon: name.value,
  ssr: true,
  id,
  customise: resolveCustomizeFn(props.customize, options.customize),
}, slots)

useId() is stable per position in the component tree, on the server and the client. Note #310 / #356 (hydration mismatch with useId() next to <Icon />): those were about <Icon /> shifting other components' useId() values. They were fixed in f5e74f5, so calling useId() here should be safe, but it's worth a test.

I'm happy to open a PR.

Workaround

Pass the id from a wrapper component:

<script setup lang="ts">
defineProps<{ name: string }>()
const iconId = useId()
</script>

<template>
  <Icon :id="iconId" :name="name" />
</template>

With this, repeated renders of the same page are byte-identical (verified on Vercel together with a fix for Nuxt's payload key order).

Dominant language
TypeScript
Stars
1.2k
Forks
103
Avg merge
3d 6h
Merged PRs (30d)
32

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from nuxt/icon

All issues in nuxt/icon

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.