Experimental SVG optimization

Type: SvgOptimizer
Default: false

Added in: astro@5.16.0

This experimental feature enables automatic optimization of your SVG components at build time.

When enabled, your imported SVG files used as components will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.

To enable this feature, import the svgoOptimizer() helper in your Astro config and assign it to the experimental svgOptimizer flag:

astro.config.mjs

import { defineConfig, svgoOptimizer } from "astro/config";

export default defineConfig({
  experimental: {
    svgOptimizer: svgoOptimizer()
  }
});

Usage

No change to using SVG components is required to take advantage of this feature. With experimental SVG optimization enabled, all your SVG component import files will be automatically optimized:

src/pages/index.astro

---
import Logo from '../assets/logo.svg';
---

<Logo />

The SVG will be optimized during the build process, resulting in smaller file sizes in your production build.

Note that this optimization applies to every SVG component import in your project. It is not possible to opt out on a per-component basis.

SVGO

Astro provides one built-in optimizer using SVGO:

import { svgoOptimizer } from "astro/config"

Configuration

You can pass an object containing SVGO configuration options to customize optimization behavior:

svgoOptimizer({
  multipass: true,
  floatPrecision: 2,
  plugins: [
    'preset-default',
    'removeXMLNS',
    {
      name: "removeXlink",
      params: {
        includeLegacy: true
      }
    }
  ]
});

plugins

Type: Array<string | PluginConfig>
Default: []

An array of SVGO plugins that will be used to optimize your SVG component imports.

This can include SVGO’s preset-default plugin collection, individual built-in plugins, or custom plugins.

To use a plugin’s default configuration, add its name to the array. If you need more control, use the overrides parameter to customize specific plugins within preset-default, or pass an object with a plugin’s name to override its individual parameters.

svgoOptimizer({
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          convertPathData: false,
          convertTransform: {
            degPrecision: 1,
            transformPrecision: 3
          },
          inlineStyles: false
        },
      },
    },
    'removeXMLNS',
    {
      name: "removeXlink",
      params: {
        includeLegacy: true
      }
    }
  ]
});

Other configuration options

There are a few SVGO configuration options, especially floatPrecision and multipass, that can be passed directly to your config object:

svgoOptimizer({
  multipass: true,
  floatPrecision: 2,
});

The multipass option sets whether to run the optimization engine multiple times until no further optimizations are found. The floatPrecision option sets the number of decimal places to preserve globally, but can be overridden for a specific plugin by specifying a custom value in its params property.

Common use cases

SVGO provides an extensive default plugin list with opinionated optimizations. While using this preset is more convenient than adding each plugin individually, you may need to customize it further. For example, it may remove items or clean up too aggressively for your situation, especially when using animations.

Preserve specific attributes

You may want to preserve certain SVG attributes and elements, such as <style>, that SVGO inlines or removes by default:

svgoOptimizer({
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          inlineStyles: false, // Preserve style elements for CSP hashing
          removeDesc: false // Keep element regardless of contents
        }
      }
    }
  ]
});

Remove specific elements

You can configure plugins to remove specific unwanted elements like metadata or hidden layers. Note that many plugins are already included in preset-default, so you typically only need to configure their behavior:

svgoOptimizer({
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeHiddenElems: {
            isHidden: false,
            displayNone: false
          }
        },
      },
    },
    'removeRasterImages'
  ]
});

Optimize for inlining in modern HTML5

Inline SVG does not require the xmlns attribute and can be safely converted to the SVG 2 specification. The removeXMLNS and removeXlink plugins are recommended for this purpose:

svgoOptimizer({
  plugins: [
    'preset-default',
    'removeXMLNS',
    {
      name: "removeXlink",
      params: {
        includeLegacy: true
      }
    }
  ]
});

Building an SVG optimizer

Added in: astro@6.2.0 Beta

The preferred method for implementing a custom SVG optimizer is to export a function that returns the SvgOptimizer object and takes the configuration as a parameter:

import type { SvgOptimizer } from "astro";
import { optimize, type Options } from "./optimizer";

export function mySvgOptimizer(options?: Options): SvgOptimizer {
  return {
    name: "my-optimizer",
    optimize: (contents) => optimize(contents, options),
  }
}

name

Type: string

A unique name for the optimizer, used in logs.

optimize()

Type: (contents: string) => string | Promise<string>

Processes the SVG contents.

How it works

SVG optimization happens during the build process, not at runtime:

• In development mode, SVG files are not optimized to ensure faster rebuild times and a smoother development experience.
• In production builds, all imported SVG files are optimized once during the build process, resulting in smaller file sizes.
• There is no runtime overhead - optimized SVGs are served as pre-processed static assets.

While the optimization process may slightly increase your build times, the result is smaller file sizes and faster page loads for your users.