@cdx-ui/icons

Cross-platform icon library for Forge UI, built on Material Symbols (outlined style, weight 400, optical size 24). Renders via react-native-svg and targets iOS, Android, and Web from a single codebase.

The full Material Symbols outlined set is available, with outlined and filled variants for each icon, plus support for custom SVGs. Browse the complete library in the icon browser.

Installation

pnpm add @cdx-ui/icons

Peer dependencies

Usage

import { Home, Favorite, Settings } from '@cdx-ui/icons';

// Outlined (default)
<Home size={24} color="blue" />

// Filled variant
<Favorite size={24} color="red" filled />

// Toggle between variants
<Home filled={isActive} />

Each icon is a forwardRef component that accepts all standard SvgProps plus the props below.

Props

All other props are spread onto the root <Svg> element, including standard React Native accessibility props.

Factory and types

Naming conventions

Every icon is available under three export patterns:

import { Home } from '@cdx-ui/icons';
import { HomeIcon } from '@cdx-ui/icons';
import { CdxHome } from '@cdx-ui/icons';

Aliases

Icons can have metadata-driven aliases defined in icon-metadata.json. Aliases let you reference the same underlying icon under alternative names — useful for legacy compatibility, domain-specific terminology, or aligning with names used by other icon sets. The generation script produces alias re-exports alongside the standard exports, so aliases are zero-cost at runtime.

Each entry in icon-metadata.json maps a base icon name (matching its SVG filename) to an array of aliases. An alias can be a plain string or an object with deprecated: true and a deprecationReason to flag names that should be migrated away from.

// icon-metadata.json
{
  "home": {
    "aliases": [
      "house",
      {
        "name": "old-home-icon",
        "deprecated": true,
        "deprecationReason": "Renamed to Home",
      },
    ],
  },
  "settings": {
    "aliases": ["gear", "preferences"],
  },
}

The config above produces the following behavior:

• House, HouseIcon, and CdxHouse all resolve to the Home icon
• Gear and Preferences resolve to the Settings icon
• OldHomeIcon resolves to Home but shows a @deprecated Renamed to Home JSDoc warning in your editor, nudging consumers toward the canonical name

import { House } from '@cdx-ui/icons'; // alias → Home
import { Gear } from '@cdx-ui/icons'; // alias → Settings
import { OldHomeIcon } from '@cdx-ui/icons'; // deprecated alias → Home (editor warning)

Aliases that collide with an existing base icon name are silently skipped during generation to avoid duplicate exports.

Country flags

Country flags are exported from the @cdx-ui/icons/flags subpath, not from the main @cdx-ui/icons barrel. Each flag is a ForgeIcon. An alpha-2 code keeps its letters in the component name, such as FlagUS or FlagXK. A subdivision code replaces the hyphen with an underscore in the component name (FlagGB_ENG for GB-ENG). The subpath also exports a flags record keyed by the code, hyphen included, and a FlagCode union. FlagCode matches the country-flag-icons 3x2 set this package was built with, including the unofficial codes that package ships for libphonenumber-js.

Each flag path has an explicit fill, so the artwork keeps its source colors. Text color classes and theme tokens do not recolor it.

CountryFlag from @cdx-ui/components is the component for product UI, including the leading slot of a country select. It resolves artwork through the flags record, so rendering CountryFlag bundles every flag. An app that shows one fixed flag can import that icon instead:

import { FlagUS, flags, type FlagCode } from '@cdx-ui/icons/flags';

<FlagUS />;

const Flag = flags.US;

Accessibility

Icons are decorative by default — hidden from assistive technology when no accessibilityLabel is provided. This is the correct behavior for icons next to text labels or inside labeled containers.

// Decorative (default) — screen readers skip this
<Home size={20} color={theme.colors.icon} />

// Informative — screen readers announce "Home, image"
<Home size={20} accessibilityLabel="Home" />

Cross-platform behavior:

• iOS (VoiceOver): Announced as "{label}, image"
• Android (TalkBack): Announced as "{label}, graphic"
• Web (React Native Web): Renders role="img" + aria-label

React Native >=0.76 aliases aria-label to accessibilityLabel, so either prop works.

For full details, see the icon accessibility guidance on the docs site.

Custom icons

Place custom SVGs in icons/custom/. The generation script reads from both icons/material/outlined/ and icons/custom/, so custom icons are treated identically to Material Symbols icons.

• Use {name}.svg for the outlined variant
• Optionally add {name}-fill.svg for a filled variant
• Author the path in the 0 -960 960 960 coordinate space. createForgeIcon forces viewBox="0 -960 960 960" on every icon, and the generator keeps only the root's child elements — it discards each SVG's own viewBox/width/height. A standard 24px export (path coordinates in 0..24) is not compatible: it renders as a tiny speck outside the viewBox (effectively invisible).
• Drawable elements must be direct children of <svg>. The parser is one level deep, so a <path> nested inside a <g> is dropped. Flatten any group (and bake its transform into the path d) before committing.

To convert a 24px brand/Figma export into the 960 grid, apply the affine transform x' = 40·x, y' = 40·y − 960 (uniform scale ×40, then translate y by −960) to the path data — e.g. with svgpath: svgpath(d).scale(40).translate(0, -960).round(2).toString(). See icons/custom/whats_app.svg for a normalized reference. Note that icons render monochrome in currentColor; any source fill is overridden by the color prop.

Brand logos

Brand logos (WhatsApp, Google, GitHub, …) are named Logo<Brand> in the Figma Icon Library, but are published without the prefix and with brand casing — e.g. Figma LogoWhatsApp → export WhatsApp. Name the SVG with the de-prefixed, snake_cased filename so the generator produces the right export:

The Code Connect batch script (repo-root scripts/generate-icon-batch.ts) strips the Logo prefix when cross-referencing Figma components against local files, so the mapping resolves automatically. Material Symbols that genuinely start with Logo (e.g. logo_dev) match by exact name first and are unaffected.

Development

Downloading Material Symbols SVGs

SVGs are fetched directly from the Google Fonts CDN by a custom download script (scripts/download-icons.ts). The script queries Google's metadata API for the active icon list, then downloads only the outlined style (weight 400, opsz 24) with both fill states. Downloaded SVGs are not checked into git.

pnpm --filter @cdx-ui/icons download-icons

This downloads an outlined and a filled SVG for every icon to icons/material/outlined/. Pass --clean to re-download from scratch instead of skipping existing files.

Generating icon components

The generation script (scripts/generate-icons.ts) reads SVGs from both icons/material/outlined/ and icons/custom/, parses them with svgson, and writes TypeScript files to src/icons/ and src/aliases/.

pnpm --filter @cdx-ui/icons generate

Generated files include:

• src/icons/{name}.ts — one file per icon with both outlined and filled path data
• src/icons/index.ts — barrel export of all icons
• src/aliases/aliases.ts — metadata-driven legacy name mappings
• src/aliases/suffixed.ts — {Name}Icon exports for every icon and alias
• src/aliases/prefixed.ts — Cdx{Name} exports for every icon and alias

Each generated icon file includes a base64-encoded @preview JSDoc tag, so hovering over an icon import in your editor shows a visual preview.

Generating bottom-tab icons

Native bottom tabs need image assets, not React components. A second generation script (scripts/generate-tab-icons.ts) rasterizes the curated subset declared in tab-icons.config.json into monochrome template PNGs (24/48/72 px → @1x/@2x/@3x) using @resvg/resvg-js, and emits platform-split descriptor modules consumed via the @cdx-ui/icons/tab-icons subpath export.

pnpm --filter @cdx-ui/icons generate:tab-icons

Generated files (gitignored, like src/icons/):

• src/tab-icons/assets/{name}[-fill][@2x|@3x].png — template PNGs (black + alpha; the tab bar tints them at runtime)
• src/tab-icons/generated/{name}.ts — web descriptor (SVG component only, no asset imports)
• src/tab-icons/generated/{name}.native.ts — native descriptor with static require() asset imports
• src/tab-icons/generated/registry.ts — TAB_ICON_NAMES tuple, TabIconName type, and TAB_ICON_COMPONENTS map
• src/tab-icons/generated/index.ts — barrel exporting descriptors + registry

To add an icon to the curated set, add its base name to tab-icons.config.json and rebuild — unknown names fail the build. Consumer-facing usage is documented in the repository's icon guide.

Tab icon registry

The generation script also emits a registry module that provides programmatic access to the curated tab icon set. The registry exports are available from the @cdx-ui/icons/tab-icons subpath:

import { TAB_ICON_NAMES, TAB_ICON_COMPONENTS, type TabIconName } from '@cdx-ui/icons/tab-icons';

// Iterate available names
TAB_ICON_NAMES.forEach((name) => console.log(name));

// Look up a component by name
const Icon = TAB_ICON_COMPONENTS['home'];

// Type-safe name parameter
function getTabIcon(name: TabIconName) {
  return TAB_ICON_COMPONENTS[name];
}

Building

pnpm --filter @cdx-ui/icons build

This runs clean -> generate -> generate:tab-icons -> bob build. A prebuild hook runs download-icons first, so a clean checkout fetches the source SVGs automatically before generation. Output goes to lib/ with three targets:

• lib/commonjs/ — CJS modules
• lib/module/ — ESM modules
• lib/typescript/ — per-file .d.ts declarations

The package is compiled by react-native-builder-bob, consistent with all other workspace packages. Unlike other workspace packages, the react-native field points to lib/module/index.js (the pre-built ESM output) rather than source. This means the icons package must be built (pnpm build:packages or pnpm --filter @cdx-ui/icons build) before Metro can resolve it. Source maps are excluded from the published package (!lib/**/*.map in files) to reduce install size.

Package structure

icons/
├── icons/
│   ├── material/outlined/     # Downloaded SVGs (not checked in)
│   └── custom/                # Hand-authored custom SVGs
├── scripts/
│   ├── download-icons.ts      # Downloads outlined SVGs from Google Fonts CDN
│   ├── generate-icons.ts      # SVG → TypeScript generation script
│   ├── generate-tab-icons.ts  # SVG → template PNG + descriptor generation
│   ├── generate-manifest.ts   # Emits icon-manifest.json (the ./manifest export)
│   └── shared.ts              # Naming utilities shared by both generators
├── src/
│   ├── icons/                 # Generated icon components
│   ├── aliases/               # Generated alias re-exports
│   ├── tab-icons/             # Bottom-tab descriptors (entry + generated assets)
│   ├── createForgeIcon.ts       # Factory function
│   ├── defaultAttributes.ts   # SVG defaults (viewBox, fill)
│   ├── types.ts               # TypeScript types
│   └── index.ts               # Main entry point
├── types/png.d.ts             # Ambient *.png module declaration (kept out of src/)
├── icon-metadata.json         # Alias and deprecation metadata
├── tab-icons.config.json      # Curated bottom-tab icon subset
├── package.json
├── tsconfig.json
└── tsconfig.build.json

src/icons/, src/aliases/, src/tab-icons/assets/, and src/tab-icons/generated/ contain generated files (gitignored except for .gitkeep sentinels).

Architecture

The package follows the patterns established by lucide-react-native, adapted for Material Symbols. Key differences:

• Fill-based icons — Material Symbols icons use fill exclusively (no stroke attributes). The color prop maps to fill.
• 960x960 coordinate system — viewBox="0 -960 960 960" instead of Lucide's 0 0 24 24. The size prop controls rendered dimensions; the viewBox handles internal coordinates.
• Outlined/filled variants — Each icon bundles both variants via the filled prop, modeling Material Symbols' fill axis. This halves the export count vs. separate components.
• Decorative by default — Icons are hidden from assistive technology unless accessibilityLabel is provided.
• OTA compatibility — childDefaultAttributes explicitly sets fill on every child SVG element, working around an inheritance bug in CodePush/expo-updates.

The full research and design rationale is recorded in the repository's icon-package research spike.