Setup

• Step 1: To install manually, run:

  npm install astro-svgs

• Step 2: Add the integration to your Astro config file (astro.config.*):

  // @ts-check
  import { defineConfig } from "astro/config";
  import svgs from "astro-svgs";
  
  export default defineConfig({
    integrations: [svgs()],
  });

• Step 3: Place your SVG files in the default src/svgs folder:

  /
  ├── src/
  │   ├── pages/
  │   │   └── index.astro
  │   └── svgs/
  │       ├── a.svg
  │       ├── b.svg
  │       └── *.svg
  └── package.json

• Step 4: Use the built-in Icon.astro component to render icons from the sprite:

  ---
  import Layout from '~/Layouts/Layout.astro';
  import { Icon } from 'astro-svgs/Icon.astro';
  ---
  <Layout>
    {/* Type hints and checks are provided by `.astro/integrations/astro-svgs/types.d.ts`. */}
    <Icon name="a" class="<CustomClassName>" />
  </Layout>

Live Access

Start the server with npm run dev, then access the virtual sprite.svg at http://localhost:4321/@svgs/sprite.svg.

Integration API

Full configuration reference

// @ts-check
import { defineConfig } from "astro/config";
import svgs from "astro-svgs";

export default defineConfig({
  build: {
    assets: "_astro",
    // assetsPrefix: env.SITE_URL,
  }
  integrations: [
    svgs({
      /**
       * Folder paths containing SVG files to generate `sprite.svg`
       * @default "src/svgs"
       */
      input: ["src/assets/sprites", "src/assets/icons"],
      /**
       * @default
       * isDev ? "beatfify" : "high"
       */
      compress: "beautify",
    }),
  ],
});

Output: The sprite file will automatically be built in config.build.assets during the build process (e.g., _astro/sprite.43a97aac.svg).

Component API

file

type: string the sprite.svg file path.

SymbolId

type: Union Type The svg file unique name you should use.

Eg1: src/components/Icon.astro

Creating a simple custom Icon.astro using the component API.

---
import { file, type SymbolId } from 'virtual:astro-svgs';
export interface Props {
    name: SymbolId;
}

const { name } = Astro.props;
---
<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
    <use xlink:href={`${file}#${name}`} xmlns:xlink="http://www.w3.org/1999/xlink" />
</svg>

The virtual module definition is automatically generated when the server starts with npm run dev and is located at .astro/integrations/astro-svgs/types.d.ts.