Importing SVG sprites into Vite-Vue setup

[Kilkenni]

I've been tinkering with using SVGs in Vite+Vue3 environment, writing in TypeScript, for a few days, and I'm confused about a specific case.

1. I've included assetsInclude: ['**/*.svg'] into vite.config.ts
2. I have a ready SVG sprite that I've placed into /public
3. Next, I import the sprite into my Vue component (I added ?url to ensure it explicitly works as a URL import, not a blob):
   import sprite from '/svg_sprite.svg?url';
4. I try to use a symbol from the sprite in the component inside <svg> like that:
   <use v-bind:href="${sprite}#logo"></use>

Result: SVG does not render properly on npm run dev, inspecting shows that the sprite gets imported as a blob (percent-encoded) anyway, despite the config parameter set in step 1) and ?url in step 3)
Disabling inlining assets globally via adding

build: {
    assetsDir: 'assets',
    assetsInlineLimit: 0, // Disable assets bundling entirely; default is 4 kB
  },

to vite.config.ts makes the SVG render properly.

Why this specific behaviour?
There are different workarounds, like using npm modules to generate virtual inline sprites etc. Some of them work, but the sprite is already ready to use and optimized, so
a) I don't see the point in adding a specialized module to generate and optimize sprites again (if there is an npm module that can work purely as a sprite loader tho, that would do it)
b) I don't want to disable asset bundling entirely
c) I'd like to keep a sprite as a standalone file (not hardcode it into Vue components)
d) Supporting hot reload on sprite modification is a nice bonus but not vital

I suspect that Vite should already handle such a common case natively, I am probably not aware of it since I'm new to Vite and Vue. Can you explain why my approach doesn't work? What should be changed to fix it?

[JulyanXu]

I think the main issue is that /public files are not meant to be imported.

For a sprite placed at public/svg_sprite.svg, reference it as a root-served public asset instead:

<script setup lang="ts">
const sprite = `${import.meta.env.BASE_URL}svg_sprite.svg`
</script>

<template>
  <svg aria-hidden="true">
    <use :href="`${sprite}#logo`" />
  </svg>
</template>

If your app is always deployed at the domain root, /svg_sprite.svg#logo is enough. import.meta.env.BASE_URL keeps it working when Vite's base is not /.

Why your current approach behaves oddly:

• Vite's publicDir is served at / during dev and copied as-is during build. The docs say public assets should be referenced with root absolute paths, not imported.
• assetsInclude is not needed for SVG here. SVG is already handled as an asset type.
• ?url is for imported assets in the module graph. If the SVG is imported from src/assets, small assets can still become data URLs depending on the inline limit. A data URL plus #symbol-id is not a good external sprite reference, which is why assetsInlineLimit: 0 appears to fix it globally.

So the simplest native Vite setup is: keep the ready-made sprite in public, do not import it, and point <use> at /svg_sprite.svg#logo (or import.meta.env.BASE_URL + 'svg_sprite.svg#logo').

[aymenhmaidiwastaken]

Files in /public are not meant to be imported — they're served as static assets at the root URL. The ?url import suffix only works for files inside /src or other source directories that go through Vite's pipeline.

For SVG sprites in /public, just reference them directly by path:

<template>
  <svg>
    <use href="/svg_sprite.svg#icon-name" />
  </svg>
</template>

No import needed. Vite serves everything in /public at the root, so /svg_sprite.svg just works.

If you want to import the sprite (for hashing, tree-shaking, etc.), move it to /src/assets/:

<script setup lang="ts">
import spriteUrl from '@/assets/svg_sprite.svg?url';
</script>

<template>
  <svg>
    <use :href="`${spriteUrl}#icon-name`" />
  </svg>
</template>

TL;DR:

• /public files → reference by absolute path, no import
• /src/assets files → import with ?url suffix

Don't mix the two. The assetsInclude config doesn't change this — it controls which file types Vite treats as assets during import, but /public is always served raw.

[Kilkenni]

This is interesting, because I've tried your approach before. To ensure, I've checked it just now:

1. moved svg_sprite.svg to /src/assets
2. rewrote import as:
   import spriteURL from '@/assets/svg_sprite.svg?url';
3. changed use to:
   <use :href="${spriteURL}#logo" class="color-accent"></use>
4. Launched via npm run dev and cleared browser cache just in case

Result: the sprite is imported into <use> as a blob anyway, and the symbol from it does not render.

However, @JulyanXu and your option to reference directly via path (if the sprite is in /public) did work. @JulyanXu 's BASE_URL note was important since my app is not deployed at the domain root.

As I remembered, I switched to /public precisely because importing as an asset didn't work.
So I guess the question can be changed to "referencing from public works, importing from assets does not — why?"

[mg1986jp]

The issue is that ?url doesn't actually prevent inlining when the file is under the assetsInlineLimit threshold. In dev mode, Vite serves everything as modules and the ?url suffix gives you a URL, but it's still processed through Vite's asset pipeline which can transform it.

Since your sprite is in /public, you shouldn't import it at all — files in public/ are served as-is and available at the root URL. Just reference it directly:

<template>
  <svg>
    <use href="/svg_sprite.svg#logo"></use>
  </svg>
</template>

No import needed. The /public/svg_sprite.svg file is served at /svg_sprite.svg by both the dev server and the production build. This avoids the entire inlining/bundling pipeline.

The problem with your approach: importing from /public with import sprite from '/svg_sprite.svg?url' tells Vite to process the file as a module, which runs it through the asset pipeline — even with ?url. For <use href> to work correctly, the browser needs to fetch the sprite as a standalone file, not as an inlined data URI. That's why disabling assetsInlineLimit fixed it.

If you want the sprite in src/assets/ instead of public/ (for cache busting via hashed filenames), you need to force it to be emitted as a file:

<script setup lang="ts">
import spriteUrl from '@/assets/svg_sprite.svg?url'
</script>

<template>
  <svg>
    <use :href="`${spriteUrl}#logo`"></use>
  </svg>
</template>

And in vite.config.ts, ensure the SVG exceeds the inline limit:

build: {
  assetsInlineLimit: 0, // for SVGs only, use a custom plugin instead
}

Or better — use a targeted approach with a plugin that only disables inlining for your sprite:

// vite.config.ts
export default defineConfig({
  plugins: [{
    name: 'no-inline-sprite',
    enforce: 'pre',
    load(id) {
      if (id.includes('svg_sprite.svg')) {
        return null; // skip inlining, let it be a file
      }
    }
  }]
})

But honestly, keeping the sprite in public/ and using a direct href is the simplest and most correct approach.

[Kilkenni]

In dev mode, Vite serves everything as modules and the ?url suffix gives you a URL

Is this the intentional design in Vite? Because it feels counterintuitive. I think one can reasonably expect Vite to give the same results for dev and build+preview in this case.
Is it worth posting a feature request to change that?