0
# @svgr/plugin-svgo
1

2
@svgr/plugin-svgo is an SVGR plugin that optimizes SVG files using SVGO (SVG Optimizer) before they are transformed into React components. It integrates seamlessly with the SVGR ecosystem to provide SVG optimization capabilities including minification, cleaning up unused elements, and applying various optimization transforms. The plugin supports flexible configuration through cosmiconfig, allowing users to customize SVGO settings via various configuration files or through SVGR's configuration system.
3

4
## Package Information
5

6
- **Package Name**: @svgr/plugin-svgo
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev @svgr/plugin-svgo`
10

11
## Core Imports
12

13
```typescript
14
import svgoPlugin from "@svgr/plugin-svgo";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const svgoPlugin = require("@svgr/plugin-svgo");
21
```
22

23
The package only exports the default plugin function. The `getSvgoConfig` function is internal and not exposed in the public API.
24

25
## Basic Usage
26

27
### As SVGR Plugin
28

29
```typescript
30
import { transform } from "@svgr/core";
31
import svgoPlugin from "@svgr/plugin-svgo";
32

33
const svgCode = `<svg xmlns="http://www.w3.org/2000/svg" width="88px" height="88px" viewBox="0 0 88 88">
34
  <title>My Icon</title>
35
  <g>
36
    <path d="M10,10 L50,50" fill="red"/>
37
  </g>
38
</svg>`;
39

40
const result = await transform(
41
  svgCode,
42
  {
43
    plugins: [svgoPlugin],
44
    svgo: true,
45
  },
46
  { componentName: "MyIcon" }
47
);
48
```
49

50
### SVGR Configuration
51

52
**.svgrrc**
53

54
```json
55
{
56
  "plugins": ["@svgr/plugin-svgo"],
57
  "svgo": true,
58
  "runtimeConfig": true
59
}
60
```
61

62
## Capabilities
63

64
### SVGO Plugin Function
65

66
Main plugin function that optimizes SVG code using SVGO as part of the SVGR transformation pipeline.
67

68
```typescript { .api }
69
/**
70
 * SVGR plugin that optimizes SVG code using SVGO
71
 * @param code - SVG source code to optimize
72
 * @param config - SVGR configuration object
73
 * @param state - SVGR state containing file path and component metadata  
74
 * @returns Optimized SVG code
75
 */
76
function svgoPlugin(code: string, config: Config, state: State): string;
77
```
78

79
The plugin:
80
- Returns original code unchanged if `config.svgo` is false
81
- Applies SVGO optimization with resolved configuration
82
- Throws errors for invalid SVG syntax
83
- Preserves viewBox for icon mode and when dimensions are disabled
84
- Configures inline styles handling for React Native mode
85

86
### Configuration Resolution
87

88
The plugin internally resolves SVGO configuration from multiple sources with priority-based loading:
89

90
1. `config.svgoConfig` - Direct SVGO configuration (highest priority)
91
2. Runtime configuration files (when `config.runtimeConfig` is true)
92
3. Generated configuration based on SVGR options (fallback)
93

94
## Configuration Options
95

96
### SVGR Config Properties
97

98
```typescript { .api }
99
interface Config {
100
  /** Enable/disable SVGO optimization */
101
  svgo?: boolean;
102
  /** Direct SVGO configuration object */
103
  svgoConfig?: SvgoConfig;
104
  /** Enable runtime configuration file loading */
105
  runtimeConfig?: boolean;
106
  /** Icon mode - preserves viewBox */
107
  icon?: boolean | string | number;
108
  /** Dimensions handling - when false, preserves viewBox */
109
  dimensions?: boolean;
110
  /** React Native mode - configures inline styles handling */
111
  native?: boolean;
112
  // ... other SVGR config properties
113
}
114

115
interface State {
116
  /** File path for configuration resolution and error context */
117
  filePath?: string;
118
  /** Component name for the generated React component */
119
  componentName: string;
120
  caller?: {
121
    name?: string;
122
    previousExport?: string | null;
123
    defaultPlugins?: ConfigPlugin[];
124
  };
125
}
126
```
127

128
### Runtime Configuration Files
129

130
When `runtimeConfig` is enabled, the plugin searches for SVGO configuration in:
131

132
- `package.json` (svgo property)
133
- `.svgorc`
134
- `.svgorc.js`, `.svgorc.json`
135
- `.svgorc.yaml`, `.svgorc.yml`
136
- `svgo.config.js`, `svgo.config.cjs`
137
- `.svgo.yml`
138

139
### Default SVGO Configuration
140

141
Generated configuration based on SVGR options:
142

143
```typescript { .api }
144
interface DefaultSvgoConfig {
145
  plugins: [
146
    {
147
      name: "preset-default";
148
      params: {
149
        overrides: {
150
          /** Preserves viewBox when icon mode or dimensions disabled */
151
          removeViewBox?: false;
152
          /** Configures inline styles for React Native */
153
          inlineStyles?: {
154
            onlyMatchedOnce: false;
155
          };
156
        };
157
      };
158
    },
159
    "prefixIds"
160
  ];
161
}
162
```
163

164
## Usage Examples
165

166
### Custom SVGO Configuration
167

168
```typescript
169
import { transform } from "@svgr/core";
170
import svgoPlugin from "@svgr/plugin-svgo";
171

172
const result = await transform(
173
  svgCode,
174
  {
175
    plugins: [svgoPlugin],
176
    svgo: true,
177
    svgoConfig: {
178
      plugins: [
179
        {
180
          name: "preset-default",
181
          params: {
182
            overrides: {
183
              removeDesc: false, // Keep descriptions
184
              removeTitle: false, // Keep titles
185
            },
186
          },
187
        },
188
        "prefixIds",
189
      ],
190
    },
191
  },
192
  { componentName: "CustomIcon" }
193
);
194
```
195

196
### Icon Mode (Preserves ViewBox)
197

198
```typescript
199
const result = await transform(
200
  svgCode,
201
  {
202
    plugins: [svgoPlugin],
203
    svgo: true,
204
    icon: true, // Preserves viewBox for proper scaling
205
  },
206
  { componentName: "IconComponent" }
207
);
208
```
209

210
### React Native Mode
211

212
```typescript
213
const result = await transform(
214
  svgCode,
215
  {
216
    plugins: [svgoPlugin],
217
    svgo: true,
218
    native: true, // Configures inline styles for React Native
219
  },
220
  { componentName: "NativeIcon" }
221
);
222
```
223

224
### Runtime Configuration
225

226
```typescript
227
// .svgorc.js in project root
228
module.exports = {
229
  plugins: [
230
    {
231
      name: "preset-default",
232
      params: {
233
        overrides: {
234
          removeViewBox: false,
235
          cleanupIds: false,
236
        },
237
      },
238
    },
239
    "prefixIds",
240
  ],
241
};
242

243
// SVGR usage
244
const result = await transform(
245
  svgCode,
246
  {
247
    plugins: [svgoPlugin],
248
    svgo: true,
249
    runtimeConfig: true, // Enables loading of .svgorc.js
250
  },
251
  { 
252
    componentName: "ConfiguredIcon",
253
    filePath: "/path/to/icon.svg" // Used for config discovery
254
  }
255
);
256
```
257

258
## Error Handling
259

260
The plugin handles errors by:
261
- Returning original code if `config.svgo` is false
262
- Throwing SVGO modernError for invalid SVG syntax
263
- Gracefully handling missing configuration files
264
- Providing descriptive error messages for configuration issues
265

266
Common error scenarios:
267
- Invalid SVG markup (malformed XML)
268
- Missing or inaccessible configuration files
269
- Invalid SVGO plugin configurations