Browser API
This document explains how to use SVGFusion in the browser to convert SVG strings to component code without writing files.
Usage for Development (TypeScript & Imports)
Both svgfusion/browser
and svgfusion-dom
are designed for easy development and type-safe usage:
- TypeScript Support: All main types (conversion options, results, framework-specific options, etc.) are exported for direct use in your code and IDE.
- Consistent API: Both packages export the same API and types, so you can switch between them without changing your code.
- Import Examples:
// For the main bundle (includes Node.js and browser support)
import {
convertToReact,
convertToVue,
extractColors,
validateSvg,
SVGFusionBrowser,
type BrowserConversionOptions,
type BrowserConversionResult,
type ReactGeneratorOptions,
type VueGeneratorOptions,
} from 'svgfusion/browser';
// For browser-optimized usage (smaller bundle)
import {
convertSvg,
extractColors,
validateSvg,
type BrowserConversionOptions,
type BrowserConversionResult,
type ReactGeneratorOptions,
type VueGeneratorOptions,
} from 'svgfusion-dom';
Tip: Use these type exports for type-safe options, results, and framework-specific settings in your development workflow. Both packages are fully compatible with modern TypeScript tooling and IDEs.
Available Types
Core Types
// Main interfaces
type BrowserConversionOptions
type BrowserConversionResult
type SVGFusionOptions
type ConversionResult
// Framework-specific
type ReactGeneratorOptions
type VueGeneratorOptions
// Utility functions
formatComponentName, pascalCase, sanitizeComponentName, svgToComponentName
// Classes and functions
SVGFusionBrowser
convertToReact, convertToVue, convertBatch
extractColors, validateSvg
Usage Pattern
import {
convertToReact,
type BrowserConversionOptions,
type BrowserConversionResult,
} from 'svgfusion/browser'; // or 'svgfusion-dom'
const options: BrowserConversionOptions = {
framework: 'react',
typescript: true,
};
const result: BrowserConversionResult = await convertToReact(
svgContent,
options
);
Package Options
SVGFusion provides two approaches for browser usage:
Option 1: svgfusion
(Main Package)
The complete toolkit including browser support:
npm install svgfusion
import { convertToReact, convertToVue } from 'svgfusion/browser';
Option 2: svgfusion-dom
(Browser-Optimized)
Dedicated browser package with smaller bundle size:
npm install svgfusion-dom
import { convertSvg } from 'svgfusion-dom';
Recommendation: Use
svgfusion-dom
for web applications where bundle size matters. Usesvgfusion/browser
when you also need Node.js features in the same project.
Browser Usage with Main Package (svgfusion/browser
)
Basic Usage
import { convertToReact, convertToVue, extractColors } from 'svgfusion/browser';
// Convert to React component
const svgContent = `<svg viewBox="0 0 24 24"><path d="M12 2l10 5v10l-10 5L2 17V7z" fill="#3B82F6"/></svg>`;
const reactResult = await convertToReact(svgContent, {
componentName: 'MyIcon',
prefix: 'UI',
suffix: 'Component',
typescript: true,
splitColors: true,
memo: true,
});
console.log(reactResult.code);
// Generated React component code as string
// Convert to Vue component
const vueResult = await convertToVue(svgContent, {
componentName: 'MyIcon',
prefix: 'My',
suffix: 'Widget',
typescript: true,
sfc: true,
scriptSetup: true,
});
console.log(vueResult.code);
// Generated Vue component code as string
// Note: The library automatically adds hyphen separators
// 'UI' + 'MyIcon' + 'Component' becomes 'UI-MyIcon-Component' then 'UIMyIconComponent'
Advanced Usage with SVGFusionBrowser Class
import { SVGFusionBrowser } from 'svgfusion/browser';
const browser = new SVGFusionBrowser();
// Convert single SVG
const result = await browser.convert(svgContent, {
framework: 'react',
typescript: true,
componentName: 'MyIcon',
splitColors: true,
fixedStrokeWidth: true,
memo: true,
forwardRef: true,
});
// Extract colors from SVG
const colors = browser.extractColors(svgContent);
console.log(colors); // ['#3B82F6', '#1E40AF', ...]
// Validate SVG
const validation = browser.validate(svgContent);
console.log(validation); // { valid: true, errors: [] }
Batch Conversion
import { convertBatch } from 'svgfusion/browser';
const svgContents = [
{ content: '<svg>...</svg>', name: 'IconHome' },
{ content: '<svg>...</svg>', name: 'IconUser' },
{ content: '<svg>...</svg>', name: 'IconStar' },
];
const results = await convertBatch(svgContents, {
framework: 'react',
typescript: true,
splitColors: true,
});
results.forEach(result => {
console.log(`${result.componentName}: ${result.code}`);
});
Generate Index Files
import { SVGFusionBrowser } from 'svgfusion/browser';
const browser = new SVGFusionBrowser();
// Convert multiple SVGs
const results = await browser.convertBatch(svgContents, options);
// Generate index file content
const indexContent = browser.generateIndexFile(results, {
exportType: 'named', // or 'default'
typescript: true,
});
console.log(indexContent);
// Generated index.ts content for tree-shaking
API Reference
convertToReact(svgContent, options)
Converts SVG to React component string.
Parameters:
svgContent
(string): SVG content to convertoptions
(BrowserConversionOptions): Conversion options
Returns: Promise<BrowserConversionResult>
convertToVue(svgContent, options)
Converts SVG to Vue component string.
Parameters:
svgContent
(string): SVG content to convertoptions
(BrowserConversionOptions): Conversion options
Returns: Promise<BrowserConversionResult>
convertBatch(svgContents, options)
Converts multiple SVGs to components.
Parameters:
svgContents
(Array): Array of{ content: string, name: string }
options
(BrowserConversionOptions): Conversion options
Returns: Promise<BrowserConversionResult[]>
extractColors(svgContent)
Extracts unique colors from SVG.
Parameters:
svgContent
(string): SVG content to analyze
Returns: string[]
- Array of color values
validateSvg(svgContent)
Validates SVG content.
Parameters:
svgContent
(string): SVG content to validate
Returns: { valid: boolean, errors: string[] }
TypeScript Support
Both svgfusion/browser
and svgfusion-dom
packages provide comprehensive TypeScript support with shared type definitions.
Note: Both packages use identical TypeScript types since
svgfusion/browser
re-exports everything fromsvgfusion-dom
.
Core Types
BrowserConversionOptions
Main configuration interface for browser conversions:
interface BrowserConversionOptions extends SVGFusionOptions {
framework: 'react' | 'vue';
typescript?: boolean;
componentName?: string;
prefix?: string;
suffix?: string;
splitColors?: boolean;
splitStrokeWidths?: boolean;
fixedStrokeWidth?: boolean;
normalizeFillStroke?: boolean;
memo?: boolean; // React only
forwardRef?: boolean; // React only
sfc?: boolean; // Vue only - Single File Component
scriptSetup?: boolean; // Vue only - <script setup>
optimize?: boolean;
}
BrowserConversionResult
Result interface with browser-specific metadata:
interface BrowserConversionResult extends ConversionResult {
code: string;
componentName: string;
filename: string;
framework: 'react' | 'vue';
typescript: boolean;
dependencies: string[];
metadata: {
originalColors: string[];
originalStrokeWidths: string[];
optimizationApplied: boolean;
features: string[];
};
}
Framework-Specific Types
React Generator Options
interface ReactGeneratorOptions extends GeneratorOptions {
memo?: boolean; // Use React.memo()
forwardRef?: boolean; // Use forwardRef()
propTypes?: boolean; // Generate PropTypes
defaultProps?: boolean; // Generate defaultProps
namedExport?: boolean; // Export as named export
}
Vue Generator Options
interface VueGeneratorOptions extends GeneratorOptions {
composition?: boolean; // Use Composition API
scriptSetup?: boolean; // Use <script setup>
sfc?: boolean; // Single File Component format
defineComponent?: boolean; // Wrap with defineComponent()
useDefineOptions?: boolean; // Vue 3.3+ compatibility
}
Core Engine Types
SVGFusionOptions
Base configuration interface:
interface SVGFusionOptions {
framework: 'react' | 'vue';
transformation?: TransformationOptions;
generator?: GeneratorOptions;
}
TransformationOptions
Controls SVG processing and optimization:
interface TransformationOptions {
optimize?: boolean; // Apply SVGO optimizations
splitColors?: boolean; // Extract colors as props
splitStrokeWidths?: boolean; // Extract stroke widths as props
fixedStrokeWidth?: boolean; // Fix stroke width scaling
normalizeFillStroke?: boolean; // Normalize fill/stroke attributes
accessibility?: boolean; // Add accessibility features
removeComments?: boolean; // Remove SVG comments
removeDuplicates?: boolean; // Remove duplicate elements
minifyPaths?: boolean; // Minify path data
}
SVG AST Types
SVGElement
Basic SVG element structure:
interface SVGElement {
tag: string;
attributes: Record<string, string>;
children: SVGElement[];
content?: string;
}
SVGAst
Complete SVG document structure:
interface SVGAst {
root: SVGElement;
viewBox?: string;
width?: string;
height?: string;
namespace?: string;
}
Feature Types
ColorMapping
For color splitting functionality:
interface ColorMapping {
originalColor: string;
variableName: string;
type: 'fill' | 'stroke' | 'stop-color';
}
StrokeWidthMapping
For stroke width splitting:
interface StrokeWidthMapping {
originalStrokeWidth: string;
variableName: string;
}
ParsedColor
Color extraction data:
interface ParsedColor {
value: string;
type: 'fill' | 'stroke' | 'stop-color';
element: SVGElement;
attribute: string;
}
Validation Types
ValidationResult
SVG validation result:
interface ValidationResult {
valid: boolean;
errors: string[];
warnings?: string[];
}
Utility Types
Type Helpers
// Component naming utilities
type ComponentName = string;
type PascalCase<T extends string> = string;
type CamelCase<T extends string> = string;
// Framework discrimination
type FrameworkOptions<T extends 'react' | 'vue'> = T extends 'react'
? ReactGeneratorOptions
: VueGeneratorOptions;
// Result type based on framework
type FrameworkResult<T extends 'react' | 'vue'> = BrowserConversionResult & {
framework: T;
};
API Type Examples
svgfusion-dom Usage
import {
convertSvg,
BrowserConversionOptions,
BrowserConversionResult,
ValidationResult,
} from 'svgfusion-dom';
// Type-safe conversion
const options: BrowserConversionOptions = {
framework: 'react',
typescript: true,
splitColors: true,
memo: true, // Only available for React
};
const result: BrowserConversionResult = await convertSvg(svgContent, options);
// Validation with types
const validation: ValidationResult = validateSvg(svgContent);
svgfusion/browser Usage
import {
convertToReact,
convertToVue,
BrowserConversionOptions,
BrowserConversionResult,
} from 'svgfusion/browser';
// React-specific conversion
const reactOptions: BrowserConversionOptions = {
framework: 'react',
typescript: true,
memo: true,
forwardRef: true,
};
const reactResult: BrowserConversionResult = await convertToReact(
svgContent,
reactOptions
);
// Vue-specific conversion
const vueOptions: BrowserConversionOptions = {
framework: 'vue',
typescript: true,
sfc: true,
scriptSetup: true,
};
const vueResult: BrowserConversionResult = await convertToVue(
svgContent,
vueOptions
);
Importing Types
Both packages export all TypeScript types for external use:
From svgfusion-dom
:
import type {
// Main API types
BrowserConversionOptions,
BrowserConversionResult,
SVGFusionOptions,
ConversionResult,
// Framework-specific types
ReactGeneratorOptions,
VueGeneratorOptions,
GeneratorOptions,
// Transformation types
TransformationOptions,
TransformationResult,
// SVG AST types
SVGElement,
SVGAst,
// Feature types
ColorMapping,
StrokeWidthMapping,
ParsedColor,
// Validation types
ValidationResult,
// Utility types
ComponentName,
FrameworkType,
} from 'svgfusion-dom';
From svgfusion/browser
:
import type {
// All types are re-exported from svgfusion-dom
BrowserConversionOptions,
BrowserConversionResult,
SVGFusionOptions,
ReactGeneratorOptions,
VueGeneratorOptions,
TransformationOptions,
ValidationResult,
// ... all other types
} from 'svgfusion/browser';
Type Definitions Reference
Enums and Literal Types
// Framework types
type FrameworkType = 'react' | 'vue';
// Color types
type ColorType = 'fill' | 'stroke' | 'stop-color';
// Export types
type ExportType = 'default' | 'named';
// Component casing
type ComponentCasing = 'PascalCase' | 'camelCase' | 'kebab-case';
Advanced Types
// Conditional types based on framework
type FrameworkSpecificOptions<T extends FrameworkType> = T extends 'react'
? ReactGeneratorOptions
: T extends 'vue'
? VueGeneratorOptions
: never;
// Result types with framework discrimination
type TypedConversionResult<T extends FrameworkType> =
BrowserConversionResult & { framework: T };
// Options with framework validation
type ValidatedOptions<T extends FrameworkType> = BrowserConversionOptions & {
framework: T;
};
Complete Type Exports
// All available exports for TypeScript users
export type {
// Core API
BrowserConversionOptions,
BrowserConversionResult,
SVGFusionOptions,
ConversionResult,
// Framework options
ReactGeneratorOptions,
VueGeneratorOptions,
GeneratorOptions,
// Transformation
TransformationOptions,
TransformationResult,
// SVG structures
SVGElement,
SVGAst,
ParsedSVG,
// Feature mapping
ColorMapping,
StrokeWidthMapping,
ParsedColor,
// Validation
ValidationResult,
ValidationError,
// Utilities
ComponentName,
FrameworkType,
ColorType,
ExportType,
ComponentCasing,
// Advanced
FrameworkSpecificOptions,
TypedConversionResult,
ValidatedOptions,
};
Type Usage Examples
Type-safe Component Creation
import type {
BrowserConversionOptions,
BrowserConversionResult,
FrameworkType,
} from 'svgfusion-dom';
// Generic function with type safety
async function createComponent<T extends FrameworkType>(
svgContent: string,
framework: T,
options?: Partial<BrowserConversionOptions>
): Promise<BrowserConversionResult & { framework: T }> {
const fullOptions: BrowserConversionOptions = {
framework,
typescript: true,
...options,
};
return (await convertSvg(
svgContent,
fullOptions
)) as BrowserConversionResult & { framework: T };
}
// Usage with type inference
const reactComponent = await createComponent(svgContent, 'react', {
memo: true,
});
const vueComponent = await createComponent(svgContent, 'vue', { sfc: true });
Custom Type Guards
import type { ValidationResult, BrowserConversionResult } from 'svgfusion-dom';
// Type guard for validation
function isValidSvg(
result: ValidationResult
): result is ValidationResult & { valid: true } {
return result.valid === true;
}
// Type guard for framework
function isReactResult(
result: BrowserConversionResult
): result is BrowserConversionResult & { framework: 'react' } {
return result.framework === 'react';
}
function isVueResult(
result: BrowserConversionResult
): result is BrowserConversionResult & { framework: 'vue' } {
return result.framework === 'vue';
}
Advanced Type Patterns
import type {
BrowserConversionOptions,
ReactGeneratorOptions,
VueGeneratorOptions,
} from 'svgfusion-dom';
// Discriminated union for framework-specific options
type FrameworkOptions =
| (BrowserConversionOptions & { framework: 'react' } & ReactGeneratorOptions)
| (BrowserConversionOptions & { framework: 'vue' } & VueGeneratorOptions);
// Helper type for extracting framework from options
type ExtractFramework<T> = T extends { framework: infer F } ? F : never;
// Utility type for framework-specific results
type ResultForFramework<T extends FrameworkOptions> =
BrowserConversionResult & { framework: ExtractFramework<T> };
Type Safety Features
- Framework Discrimination: TypeScript ensures React-only options (like
memo
) aren't used with Vue - Optional Configuration: All options have sensible defaults with optional typing
- Rich Metadata: Detailed transformation tracking with type safety
- Utility Function Types: Full TypeScript support for helper functions
- Validation Types: Structured error reporting with proper typing
- Generic Type Support: Advanced TypeScript patterns for complex use cases
- Type Guards: Runtime type checking with TypeScript integration
Usage Examples
React Component Generation
const svgContent = `
<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
<path d="M12 2L2 7V17L12 22L22 17V7L12 2Z" fill="#3B82F6" stroke="#1E40AF" stroke-width="2"/>
<path d="M12 8L8 10V14L12 16L16 14V10L12 8Z" fill="#EF4444" stroke="#DC2626" stroke-width="1"/>
</svg>
`;
const result = await convertToReact(svgContent, {
componentName: 'DiamondIcon',
typescript: true,
splitColors: true,
memo: true,
forwardRef: true,
});
// result.code contains:
// import React, { Ref, forwardRef, memo } from 'react';
// import * as React from 'react';
//
// interface DiamondIconProps extends React.SVGProps<SVGSVGElement> {
// title?: string;
// titleId?: string;
// desc?: string;
// descId?: string;
// size?: string;
// color?: string;
// colorClass?: string;
// color2?: string;
// color2Class?: string;
// color3?: string;
// color3Class?: string;
// color4?: string;
// color4Class?: string;
// }
//
// const DiamondIcon = (props: DiamondIconProps, ref: Ref<SVGSVGElement>) => {
// // Component implementation...
// };
//
// const ForwardRef = forwardRef(DiamondIcon);
// const Memo = memo(ForwardRef);
// export default Memo;
Vue Component Generation
const result = await convertToVue(svgContent, {
componentName: 'DiamondIcon',
typescript: true,
sfc: true,
scriptSetup: true,
splitColors: true,
});
// result.code contains:
// <template>
// <svg
// viewBox="0 0 24 24"
// fill="none"
// xmlns="http://www.w3.org/2000/svg"
// :width="size"
// :height="size"
// v-bind="$attrs"
// >
// <title v-if="title" :id="titleId">{{ title }}</title>
// <desc v-if="desc" :id="descId">{{ desc }}</desc>
// <!-- SVG content with dynamic colors -->
// </svg>
// </template>
//
// <script setup lang="ts">
// import type { SVGAttributes } from 'vue';
//
// interface Props extends SVGAttributes {
// title?: string;
// titleId?: string;
// desc?: string;
// descId?: string;
// size?: string;
// color?: string;
// colorClass?: string;
// // ... other color props
// }
//
// const props = withDefaults(defineProps<Props>(), {
// size: '24',
// color: '#3B82F6',
// // ... other defaults
// });
// </script>
Browser Compatibility
The browser version of SVGFusion works in all modern browsers that support:
- ES2020 features
- Promise/async-await
- ES modules
Browser Usage with Dedicated Package (svgfusion-dom
)
The svgfusion-dom
package provides a streamlined API optimized for browser usage:
Basic Usage
import { convertSvg } from 'svgfusion-dom';
const svgContent = `<svg viewBox="0 0 24 24"><path d="M12 2l10 5v10l-10 5L2 17V7z" fill="#3B82F6"/></svg>`;
// Convert to React component
const reactResult = await convertSvg(svgContent, {
framework: 'react',
componentName: 'MyIcon',
typescript: true,
splitColors: true,
});
console.log(reactResult); // Generated React component code as string
// Convert to Vue component
const vueResult = await convertSvg(svgContent, {
framework: 'vue',
componentName: 'MyIcon',
typescript: true,
sfc: true,
scriptSetup: true,
splitColors: true,
});
console.log(vueResult); // Generated Vue component code as string
Advanced Features
import {
convertSvg,
extractColors,
validateSvg,
convertBatch,
} from 'svgfusion-dom';
// Extract colors from SVG
const colors = extractColors(svgContent);
console.log(colors); // ['#3B82F6', '#1E40AF', ...]
// Validate SVG content
const validation = validateSvg(svgContent);
console.log(validation); // { valid: true, errors: [] }
// Batch conversion
const svgContents = [
{ content: '<svg>...</svg>', name: 'IconHome' },
{ content: '<svg>...</svg>', name: 'IconUser' },
];
const results = await convertBatch(svgContents, {
framework: 'react',
typescript: true,
splitColors: true,
});
CDN Usage
Both packages support CDN usage:
Main Package
<script type="module">
import {
convertToReact,
convertToVue,
} from 'https://cdn.skypack.dev/svgfusion/browser';
// Your code here
</script>
Dedicated Package
<script type="module">
import { convertSvg } from 'https://cdn.skypack.dev/svgfusion-dom';
// Your code here
</script>
Differences from Node.js Version
The browser version:
- Returns component code as strings instead of writing files
- Supports all conversion features (color splitting, stroke fixing, etc.)
- Includes validation and color extraction
- Supports batch conversion
- Can generate index file content
- Cannot read from or write to the filesystem
- Does not include CLI functionality
- Cannot process entire directories
For file-based operations, use the Node.js version of SVGFusion.