Skip to main content
Design system

Creating Custom Icons

How to use our Icon component with your own SVGs to create a custom Icon.

Table of Contents


There may be some instances where your team needs to use an icon with an asset that does not currently exist in WAM.

While we aim to help as much as we can, other commitments could mean that we are unable to add an icon to WAM within your timeframe. It is also possible that you need an icon for a domain specific use case and it does not make sense to add this asset to the system. For both of these instances, a custom icon might be what you need.


This guide assumes that you are working with ReactJS and are using the WPDS Icon Component.


  1. Double-check: Please make sure that the icon you are looking to use doesn't currently exist in WPDS. You can check Figma or go to the Icon Assets Page in our docs site to look through what assets we currently make available.

  2. Follow contribution guidelines: When creating your icon, please follow the contribution guidelines outlined in the Making an Icon section of our docs

  3. Export as SVG: Please ensure that your new icon is a SVG. In WPDS, all icons are 16x16 pixels.


  1. Add svg to repo and make it a React Component: Add the svg file to your repo and make it a React Component. There are a couple of different ways you can do this.

    • If you are going to be using a lot of SVGs in your repo, then you might consider using something like @svgr/webpack and setting up your webpack configs to convert your SVGs to React Components for you automatically.

    • You can use an online conversion tool such as SVGR Playground to convert your SVG into a React Component. You can then simply copy and paste that new component into your code.

    • You can cast your SVG into a React Component from your import statement. This might be an okay solution if you are going to be using this icon less than a handful of times. Otherwise, you might want to consider using one of the first two options.

  2. Pass SVG into the Icon component: Once you have your SVGs available to you as React Components, you can now pass them into the WPDS Icon component like you would a WPDS icon. They will behave the same.

    import * as React from "react";
    import { Icon } from "@washingtonpost/wpds-ui-kit";
    import { Bell } from "@washingtonpost/wpds-assets";
    // Casting our Crop SVG as a ReactComponent
    import { ReactComponent as Crop } from "./crop.svg";
    export default function App() {
      return (
          <Icon label="icon" size="200">
            <Bell /> //Our WPDS icon
          <Icon label="icon" size="200">
            <Crop /> //Our custom icon