Cryptocurrency Icons

BitGo fork of cryptocurrency-icons for generating SVG icons and React components used in BitGo applications.

Install

npm install @bitgo-forks/cryptocurrency-icons

Usage

SVG Icons

Import SVG files directly from the package:

// Color icons (recommended)
import btcIcon from '@bitgo-forks/cryptocurrency-icons/svg/color/btc.svg';

// Monochrome variants
import btcWhite from '@bitgo-forks/cryptocurrency-icons/svg/white/btc.svg';
import btcBlack from '@bitgo-forks/cryptocurrency-icons/svg/black/btc.svg';
import btcOutline from '@bitgo-forks/cryptocurrency-icons/svg/icon/btc.svg';

React Components

Import and use React components with the prefixId prop for ID namespacing:

import BtcIcon from '@bitgo-forks/cryptocurrency-icons/react/btc';

function MyComponent() {
  return (
    <BtcIcon 
      prefixId="unique-id" 
      width={32} 
      height={32} 
    />
  );
}

The prefixId prop prevents CSS/ID collisions when rendering multiple icons on the same page.

PNG Icons

Pre-rendered PNG icons are available in multiple sizes:

• 32/ - 32x32 pixels
• 32@2x/ - 64x64 pixels (retina)
• 128/ - 128x128 pixels

These legacy paths remain available for existing consumers. New raster-only icons that do not have an SVG representation use the explicit png/ path:

import faiIcon from '@bitgo-forks/cryptocurrency-icons/png/128/color/baseethfai.png';

Raster-only identities are declared with formats: ["png"] in manifest.json. They are not generated as SVG or React components. Runtime consumers should use the PNG CDN metadata rather than assuming every manifest entry has an SVG.

Manifest

The manifest.json file contains metadata for all icons:

{
  "symbol": "BTC",
  "name": "Bitcoin",
  "color": "#f7931a",
  "formats": ["svg"]
}

Use this for programmatic access to icon metadata, colors, display names, and available representations. Existing vector icons use formats: ["svg"]; raster-only exceptions use formats: ["png"].

Adding New Icons

1. Add your SVG to the svg/color/ directory (lowercase filename)
2. Add the symbol to manifest.json
3. Run the generation scripts:

npm install
npm run manifest
npm run generate

4. Commit both the SVG and generated React component

Adding PNG-Only Icons

Use this workflow for artwork that is not suitable for faithful vectorization. PNG-only icons are an additive format and do not create an SVG or generated React component.

1. Add the approved PNG outputs under png/:

   png/128/color/{symbol}.png
   png/32/color/{symbol}.png
   png/32@2x/color/{symbol}@2x.png
   

2. Add formats: ["png"] to the icon's manifest.json record.
3. Run:

   npm run manifest
   npm run cdn-manifest
   npm run sync-check
   npm run test:pack
   

4. Review the icon in both light and dark consumer contexts.

Do not add a PNG-only identity to svg/color/, react/, or the generated SVG React barrel. SVG-only consumers will use their normal generic fallback; raster-aware consumers use the PNG CDN metadata or the png/* package path.

The cdn-manifest.json file is generated and ignored in source control. It contains the existing SVG variant maps plus an optional png namespace for hashed PNG assets.

SVG Requirements

• Maximum file size: 100KB (recommended: <20KB)
• Format: Proper vector SVG (no embedded PNG/JPEG base64 data)
• ViewBox: Must include viewBox attribute
• Class names: Avoid generic names like cls-1 or st0 (will be auto-prefixed)

See CONTRIBUTING.md for detailed guidelines.

Scripts

Storybook (PR previews)

PRs that touch icons or Storybook run Storybook PR preview in GitHub Actions: changed SVG paths are written to stories/changed-icons.json, then a static build is synced to the dev automated-test-reports bucket under cryptocurrency-icons-ci/pr-<number>/ (same pattern as Playwright reports; not production cdn.bitgo.com). See WEB-718 / CE-9917.

Locally:

npm install
npm run storybook
# or verify a production build:
npm run test:storybook

Testing

npm test runs SVG validation, sync checks, CDN pack checks, and Storybook gallery logic unit tests (scripts/test-storybook-gallery-logic.mjs). Those tests cover manifest filename normalization, manifest lookup, and matching PR changed paths to svg/<variant>/<file>.svg (same rules as stories/helpers.ts, implemented in scripts/storybook-gallery-logic.mjs).

For Storybook UI and bundling, run npm run test:storybook (runs the gallery tests plus build-storybook). See TESTING.md for the broader validation and release checklist.

Repository Structure

cryptocurrency-icons/
├── svg/
│   ├── color/      # Full-color icons (primary)
│   ├── white/      # White monochrome
│   ├── black/      # Black monochrome
│   └── icon/       # Outline icons
├── react/          # Generated React components
├── 32/             # 32px PNG exports
├── 32@2x/          # 64px PNG exports (retina)
├── 128/            # 128px PNG exports
├── png/            # New PNG-only icon outputs
├── manifest.json   # Icon metadata, including optional formats
├── .storybook/     # Storybook config (dev + PR preview builds)
├── stories/        # Storybook stories + `changed-icons.json` (CI-filled on PRs)
└── scripts/        # Generation, validation, and tests

Contributing

See CONTRIBUTING.md for submission guidelines.

Maintainers

See MAINTAINING.md for maintainer workflows.

License

CC0-1.0 - Public Domain