astro-svgs

Overview

A compact, flexible solution for managing SVG sprites in Astro projects.

It automates symbol ID management, supports hot reloading, and generates optimized SVG sprites with minimal setup. It includes built-in components and an open API, allowing easy customization to suit your needs.

Installation

Quickly install with the astro add command:

npx astro add astro-svgs

If you run into issues, try with Manual Setup guide.

Usage

Manual Setup

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/
  │   ├── svgs/
  │   │   ├── a.svg
  │   │   ├── b.svg
  │   │   └── c.svg
  │   └── pages/
  │       └── index.astro
  └── 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`, which is automatically generated in development mode (`npm run dev`) and updated whenever the config changes. */}
    <Icon name="a" class="<CustomClassName>" />
  </Layout>
  

Live Access

Set compress to import.meta.env.DEV ? 'beautify' : 'high' for clearer SVGs in development.

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

API Reference

All configuration options are provided here.

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

export default defineConfig({
  integrations: [
    svgs({
      /**
       * Folder paths containing SVG files to generate `sprite.svg`
       * @default "src/svgs"
       */
      input: ["src/assets/sprites", "src/assets/images"],
      /**
       * @default: "high"
       */
      compress: import.meta.env.DEV ? "beautify" : "high",
    }),
  ],
});

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

Need help or Feedback?

If you have questions or feedback, feel free to submit an issue on our GitHub repository.

Changelog

For the full changelog, see the Releases page.

License

MIT