react-native-nano-icons

Nano Icons uses two distinct rendering paths on iOS to optimize performance:

Standalone Icons (Common Case)

• Detected when the icon is not inside a <Text> component.
• Draws directly in NanoIconView's drawRect:.
• Uses CTFontDrawGlyphs to render glyph layers at the cached baseline position.
• Uses a coordinate-flip transform to map CoreText's Y-up system to UIKit's Y-down frame.

Inline Icons

• Detected by checking the nearest 3 ancestors for RCTParagraphComponentView.
• Uses a lazily-created CALayer sublayer instead of a UIView to avoid the overhead of the responder chain and accessibility tree.
• The CALayer.frame.origin.y is shifted upward based on the computed baseline offset from the parent's attributedText (considering ascender, lineHeight, and NSBaselineOffsetAttributeName).
• The offset is calculated as the distance from the Yoga frame's bottom edge to the text baseline using fmod(frameBottom, lineHeight), clamped to zero if the icon is taller than the text line.

Unlike traditional color font formats (like COLRv0/COLRv1) which have inconsistent platform support and limited runtime control, Nano Icons uses a subglyph layer stacking approach.

The Mental Model

1. Decomposition: At build time, a multi-color SVG is decomposed into multiple single-color layers.
2. Subglyphs: Each layer is converted into a simple glyph and assigned a unique, private-use codepoint in a standard font file.
3. Glyph Map: A JSON metadata file maps the original icon name to its constituent layers (codepoints and default colors).
4. Runtime Rendering: The Icon component renders these subglyphs stacked using absolute positioning within a unified view box.

Advantages

• Predictability: Rendering logic is consistent across platforms because it doesn't rely on complex native color-font stacks.
• Runtime Customization: You can override the color of specific layers via props (e.g., changing a character's clothing color) without needing multiple icon assets.
• Performance: Uses the highly optimized native text rendering pipeline, which is roughly 3x faster than react-native-svg.

// Example of the generated glyphmap structure
{
  "meta": {
    "fontFamily": "string",
    "upm": 1000,
    "safeZone": 10,
    "startUnicode": 65536
  },
  "icons": {
    "iconName": {
      "adv": 1000, 
      "layers": [
        { "codepoint": 65536, "color": "#FF0000" },
        { "codepoint": 65537, "color": "#00FF00" }
      ]
    }
  }
}

The pipeline converts a directory of SVG files into a TrueType font and a glyphmap. Multi-color icons are decomposed into layers: each color layer of an icon is rendered as a separate glyph, which are then layered on top of each other at runtime.

The transformation flow:

1. SVG Input: Raw SVG files.
2. Flattening: picosvg flattens transforms, resolves <use> and <clipPath>, and converts strokes to fills.
3. Path Processing:
   • Evenodd paths are extracted and later restored to prevent contour loss during simplification.
   • Evenodd paths are converted to nonzero winding using a containment-based algorithm (calculating nesting depth via ray-casting).
   • Consecutive paths with the same color are merged into single compound paths to reduce glyph count.
4. Placement & Transformation: Paths are scaled, centered, and flipped (SVG Y-down to Font Y-up) to fit the font's upm and safeZone.
5. Output:
   • A .ttf file containing the glyphs.
   • A .glyphmap.json file mapping icon names to their codepoints and color layers.

The project uses a three-stage pipeline to transform complex SVGs into high-performance native font icons:

1. Geometry Compilation (SVG → Flattened Paths): Uses PathKit (via Pyodide/WASM) to perform heavy-duty geometry math. This stage flattens transforms, resolves clipPath via boolean operations, and simplifies contours. This ensures the geometry is "font-safe" before it reaches the font compiler. Note: SVG `` resolution is currently a known limitation.

2. Layer Extraction (Flattened Paths → Layer SVGs): A Node.js process parses the flattened SVG DOM, splits shapes into layers based on fill color, and computes placement rules (UPM scaling, safe zones). It emits one small, deterministic SVG per layer.

3. Font & Metadata Generation (Layer SVGs → Font + Glyphmap): Compiles a simple, universal glyph font (using glyf and cmap tables) and generates a glyphmap JSON file that maps icon names to their specific subglyph codepoints and default colors.

By default, icons are statically bundled into the native app. If you frequently update icons and want to use Expo Over-The-Air (OTA) updates without a full native rebuild, use linking: 'dynamic'.

1. Configure: Set linking: 'dynamic' in your iconSets config.
2. Build: The build process will still generate the .ttf and .glyphmap.json files, but they won't be linked to the native binary.
3. Runtime: You must pass the font file (via require or a uri) as the second argument to createNanoIconSet so the library can register it at runtime.

This allows you to ship new .ttf and .glyphmap.json files via an OTA update, and the app will pick them up without a new App Store/Play Store submission.

{
  "iconSets": [
    {
      "inputDir": "./assets/icons/dynamic-ota-icons",
      "linking": "dynamic"
    }
  ]
}

import { createNanoIconSet } from "react-native-nano-icons";
import glyphMap from "./dynamic-ota-icons.glyphmap.json";

// Using a local file
export const Icon = createNanoIconSet(glyphMap, require("./dynamic-ota-icons.ttf"));

// OR using a remote URI
// export const Icon = createNanoIconSet(glyphMap, { uri: "https://cdn.example.com/remote-nano-icons.ttf" });