Building a Production-Grade SVG Icon Component in React

1. Why Inline SVG Beats Every Alternative

Before diving into the code, it is critical to understand why building a bespoke React component that renders inline SVGs is vastly superior to other methods of displaying icons, such as <img> tags, CSS background images, icon fonts, or data URIs.

The traditional approaches all have severe limitations when integrated into a modern component-driven architecture:

• Icon Fonts: They suffer from poor rendering on certain operating systems, block rendering until the font file is downloaded, and make it difficult to do multi-color icons or specific sub-path animations. Worst of all, they can fail entirely if a user has custom fonts disabled or if a network request hangs.
• Image Tags & CSS Backgrounds: Using <img src="icon.svg"> or background-image: url('icon.svg') prevents you from styling the SVG internals with CSS. You cannot easily change the fill color on hover, target individual paths, or transition stroke properties.
• Data URIs: While they save a network request by embedding the SVG directly into your CSS or JS, they increase the file size significantly (Base64 encoding adds about 33% overhead) and still suffer from the same styling limitations as image tags.

Inline SVG solves all these problems. When an SVG is placed directly into the DOM tree, it becomes part of the document. This means CSS can target its nodes seamlessly. In React, this translates to components that accept props for size, color, stroke width, and animation states, propagating those values directly into the SVG markup. You gain ultimate control over styling, accessibility, and performance.

2. The Base Icon Component Architecture

To start, we need a flexible foundation. A production-grade React icon component must be fully typed, support ref forwarding (crucial for tooltips or focus management), and allow for polymorphic sizing.

Here is the architectural baseline for our Icon component:

import React, { forwardRef } from 'react';

export interface IconProps extends React.SVGAttributes<SVGSVGElement> {
  /** The SVG path or elements to render inside the SVG wrapper */
  children?: React.ReactNode;
  /** Numerical size in pixels, or string for custom units */
  size?: number | string;
  /** Stroke or fill color. Defaults to 'currentColor' */
  color?: string;
  /** Adjust the stroke width. Defaults to 2 */
  strokeWidth?: number | string;
}

export const Icon = forwardRef<SVGSVGElement, IconProps>(
  (
    {
      children,
      size = 24,
      color = 'currentColor',
      strokeWidth = 2,
      className,
      ...rest
    },
    ref
  ) => {
    return (
      <svg
        ref={ref}
        xmlns="http://www.w3.org/2000/svg"
        width={size}
        height={size}
        viewBox="0 0 24 24"
        fill="none"
        stroke={color}
        strokeWidth={strokeWidth}
        strokeLinecap="round"
        strokeLinejoin="round"
        className={`ui-icon ${className || ''}`.trim()}
        {...rest}
      >
        {children}
      </svg>
    );
  }
);

Icon.displayName = 'Icon';

Notice the use of forwardRef. Without it, wrapper components like Radix UI tooltips or Framer Motion won't be able to attach event listeners or measure the DOM node. We also spread the ...rest properties to ensure any valid SVG attributes—like aria-label or data attributes—can be passed through seamlessly.

3. Designing the Perfect Props Interface

Great component APIs are intuitive. Let's break down the prop design decisions made above:

• size: We default to 24, which maps to a standard 24x24 grid. By accepting both number and string, developers can pass size={16} or size="1.5rem" depending on their design system's spacing scale.
• color: By defaulting to currentColor, the icon automatically inherits the text color of its parent container. This makes hovering buttons or links trivial—you only need to change the parent's text color.
• strokeWidth: This allows you to adjust the visual weight of the icon. A stroke width of 1.5 feels light and elegant, while 2 or 2.5 feels bold and punchy.
• children: The actual vector paths are passed as children. This inversion of control allows the wrapper component to handle the boilerplate, while individual icons just define their unique shapes.

4. Building an Icon Registry Pattern

If your application has 300 icons, you do not want developers importing them from 300 different files and guessing the names. You need a central entry point. We accomplish this using an Icon Registry pattern.

First, define your specific icons using the base wrapper:

// icons/ChevronRight.tsx
import React from 'react';
import { Icon, IconProps } from './Icon';

export const ChevronRight = (props: IconProps) => (
  <Icon {...props}>
    <polyline points="9 18 15 12 9 6" />
  </Icon>
);

// icons/Home.tsx
export const Home = (props: IconProps) => (
  <Icon {...props}>
    <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
    <polyline points="9 22 9 12 15 12 15 22" />
  </Icon>
);

Next, export them through an index.ts barrel file, creating a clean namespace:

// icons/index.ts
export * from './ChevronRight';
export * from './Home';
export * from './Settings';
export * from './User';
// ... and so on

For dynamic rendering (e.g., a CMS where the icon name is a string), you can build a lazy-loaded dynamic registry to avoid bloating the initial payload:

// IconRenderer.tsx
import React, { lazy, Suspense } from 'react';

const iconMap = {
  home: lazy(() => import('./icons/Home').then(m => ({ default: m.Home }))),
  settings: lazy(() => import('./icons/Settings').then(m => ({ default: m.Settings }))),
};

export type IconName = keyof typeof iconMap;

interface IconRendererProps extends React.ComponentProps<'svg'> {
  name: IconName;
  fallback?: React.ReactNode;
}

export const IconRenderer = ({ name, fallback, ...props }: IconRendererProps) => {
  const Component = iconMap[name];
  
  if (!Component) return null;
  
  return (
    <Suspense fallback={fallback || <span className="icon-placeholder" />}>
      <Component {...props} />
    </Suspense>
  );
};

5. Tree-Shaking and Bundle Optimization

When you have a massive library of icons exported from an index.ts file, how do you prevent importing the whole 2MB library when you only need a single icon?

The solution is tree-shaking. Modern bundlers like Webpack, Vite (Rollup), and Turbopack rely on static ES modules (import and export) to determine which code is actually used. To ensure your icons are tree-shakeable, you must adhere to two rules:

1. Use ES module syntax (no module.exports or require).
2. Mark your package as side-effect free in package.json.

In your package.json, add:

{
  "name": "my-ui-icons",
  "version": "1.0.0",
  "sideEffects": false
}

The "sideEffects": false flag tells the bundler that none of the modules execute anything globally on initialization. If an exported icon function isn't used, the bundler can safely discard the code.

6. Accessibility Deep Dive

Icons fall into two categories for screen readers: decorative and informative. Our base icon component needs to elegantly handle both scenarios to ensure ADA compliance.

A decorative icon (e.g., an icon next to text that says "Settings") should be hidden from screen readers. An informative icon (e.g., an icon-only button without text) must announce its purpose.

Here is an upgraded accessible wrapper:

import React, { forwardRef } from 'react';

export interface AccessibleIconProps extends React.SVGAttributes<SVGSVGElement> {
  children?: React.ReactNode;
  size?: number | string;
  /** Explicit title for screen readers. If missing, icon is treated as decorative. */
  title?: string;
  /** Optional longer description for complex icons */
  desc?: string;
}

export const AccessibleIcon = forwardRef<SVGSVGElement, AccessibleIconProps>(
  ({ children, size = 24, title, desc, ...rest }, ref) => {
    const isDecorative = !title;
    
    // Generate unique IDs for aria-labelledby to avoid duplicate ID issues
    const titleId = title ? React.useId() : undefined;
    const descId = desc ? React.useId() : undefined;
    
    return (
      <svg
        ref={ref}
        width={size}
        height={size}
        viewBox="0 0 24 24"
        fill="none"
        stroke="currentColor"
        strokeWidth="2"
        strokeLinecap="round"
        strokeLinejoin="round"
        aria-hidden={isDecorative ? "true" : "false"}
        role={isDecorative ? "img" : "graphics-symbol"}
        aria-labelledby={title ? `${titleId} ${descId || ''}`.trim() : undefined}
        focusable="false" // Fixes IE11 focus bug
        {...rest}
      >
        {title && <title id={titleId}>{title}</title>}
        {desc && <desc id={descId}>{desc}</desc>}
        {children}
      </svg>
    );
  }
);

By providing a title prop, the component automatically injects the <title> element, links it via aria-labelledby, and toggles aria-hidden. This guarantees a bulletproof accessibility tree.

7. Animation Integration with Framer Motion

Static icons are functional, but animated icons delight users. Adding motion to SVG strokes or paths is straightforward. For simple interactions, use CSS transitions. For complex spring physics, Framer Motion is the standard in the React ecosystem.

Because we used forwardRef, wrapping our icons with Framer Motion's motion component just works:

import { motion } from 'framer-motion';
import { Settings } from './icons';

// Usage in a component:
export const SettingsButton = () => {
  return (
    <button className="p-2 rounded hover:bg-gray-800">
      <motion.div
        whileHover={{ rotate: 90 }}
        transition={{ type: "spring", stiffness: 200, damping: 10 }}
      >
        <Settings size={20} color="#C1DD2D" />
      </motion.div>
    </button>
  );
};

For custom path-drawing animations internally, you can define a specialized animated icon variant:

import { motion } from 'framer-motion';

export const AnimatedCheck = () => (
  <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
    <motion.polyline 
      points="20 6 9 17 4 12"
      initial={{ pathLength: 0 }}
      animate={{ pathLength: 1 }}
      transition={{ duration: 0.5, ease: "easeOut" }}
    />
  </svg>
);

8. Dark Mode & Theme-Aware Icons

By leveraging currentColor in our base component, icons automatically support dark mode assuming the parent text color adapts properly.

However, for multi-tone icons (e.g., duotone designs), you need CSS custom properties. By injecting CSS variables into the SVG paths, the colors can adapt dynamically to theme changes without passing new props to React:

/* global.css */
:root {
  --icon-primary: #1A1A1A;
  --icon-secondary: #888888;
}

[data-theme="dark"] {
  --icon-primary: #F2F2F2;
  --icon-secondary: #666666;
}

// icons/DuotoneShield.tsx
export const DuotoneShield = (props: IconProps) => (
  <Icon {...props}>
    {/* Background fill uses secondary theme variable */}
    <path 
      d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" 
      fill="var(--icon-secondary)" 
      stroke="none" 
      opacity="0.2"
    />
    {/* Stroke uses primary theme variable */}
    <path 
      d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" 
      stroke="var(--icon-primary)" 
    />
  </Icon>
);

9. Performance & Memoization

React renders are generally fast, but re-rendering hundreds of complex vector paths during state updates can cause jank. Since SVG paths are pure and deterministic based on props, they are prime candidates for React.memo().

Memoizing the icon components ensures they only re-render if their size, color, or className changes:

import React, { memo } from 'react';

const _Home = (props: IconProps) => (
  <Icon {...props}>
    <path d="..." />
  </Icon>
);

export const Home = memo(_Home);

Pro tip: While memoization is helpful, avoid passing inline object or array props to your icons (like style={{ margin: 10 }}), as this breaks the referential equality check of React.memo, causing unnecessary renders anyway.

10. Testing Your Icon Components

Icons must be tested for structural integrity and accessibility. Using Jest and React Testing Library, we can verify that our base wrapper correctly forwards attributes and dynamically computes the ARIA requirements.

import { render, screen } from '@testing-library/react';
import { AccessibleIcon } from './AccessibleIcon';

describe('AccessibleIcon Component', () => {
  it('renders a decorative icon by default', () => {
    const { container } = render(<AccessibleIcon />);
    const svg = container.querySelector('svg');
    
    expect(svg).toHaveAttribute('aria-hidden', 'true');
    expect(svg).toHaveAttribute('role', 'img');
    expect(screen.queryByTitle(/.+/)).toBeNull();
  });

  it('renders an accessible informative icon when title is provided', () => {
    render(<AccessibleIcon title="Search Database" />);
    
    const svg = screen.getByRole('graphics-symbol', { name: 'Search Database' });
    expect(svg).toHaveAttribute('aria-hidden', 'false');
    expect(svg).toHaveAttribute('aria-labelledby');
  });
});

Additionally, visual regression testing is vital for SVGs to ensure a path doesn't accidentally get malformed. Using Storybook, you can render an icon gallery that designers can review:

// IconGallery.stories.tsx
import React from 'react';
import * as Icons from './icons';

export default {
  title: 'Design System/Icons',
};

export const AllIcons = () => (
  <div className="grid grid-cols-6 gap-4 p-8">
    {Object.entries(Icons).map(([name, Icon]) => (
      <div key={name} className="flex flex-col items-center gap-2">
        <Icon size={32} className="text-gray-200" />
        <span className="text-xs text-gray-500">{name}</span>
      </div>
    ))}
  </div>
);