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

<summary>Manual Setup</summary> #### Setup - Step 1: To install manually, run:

shell
  npm install astro-svgs

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

js
  // @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:

plaintext
  /
  ├── src/
  │   ├── pages/
  │   │   └── index.astro
  │   └── svgs/
  │       ├── a.svg
  │       ├── b.svg
  │       └── *.svg
  └── astro.config.mjs

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

ts
  ---
  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.

<summary>API Reference</summary> ### Integration API Full configuration reference

js
// @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.

ts
---
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.

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

包详细信息

astro-svgs

自述文件