Use a custom icon font in Flutter with const IconData

Enumerate the generated API without maintaining a second list

Set catalog in the checked-in config when a gallery, picker, or coverage test needs every icon by its Dart name. GlyphPact adds a separate AppIconsCatalog companion to the existing generated Dart file.

AppIconsCatalog.byName is a static const map containing every base glyph in ascending codepoint order. Packs containing partial-alpha icons also receive layeredByName, which contains only their lossless layered descriptors. Their static-const descriptor provider is annotated separately so a direct reference to one layered icon does not retain its siblings.

Generated regions whose cross-version layout differs remain stable under dart format. The narrow controls cover the catalog, layered descriptors, and an over-width base provider when needed. Dart 3.0 through 3.6 formatters ignore them but receive legacy-canonical layout; Dart 3.7 and later honor them.

Tree shaking, precisely

The base provider is emitted the way Flutter's icon subsetting requires: an abstract final class annotated@flutter.staticIconProvider with only static const members. Partial-alpha packs apply the same annotation to their static-const descriptor provider. The catalog companion also has only static const members and carries the provider annotation so unreachable catalog declarations are ignored.

The optional catalog remains outside the base provider namespace. Its annotation suppresses declaration-only constants, but reachable map values remain visible to Flutter. Enabling it does not itself enlarge a release: when the catalog is unreachable, Flutter removes it and subsets from the individual provider constants used by the app.

Making byName reachable retains every base glyph. Making layeredByName reachable retains those icons' fallbacks and layer-font glyphs. A catalog imported only by tests has no release cost.

What GlyphPact does and does not control. It emits a provider that satisfies the contract. Whether subsetting actually runs is your build's decision: it applies to release builds and is disabled by --no-tree-shake-icons. ConstructingIconData from a variable anywhere else in your app is the usual reason subsetting gets switched off.

Shipping icons from a Dart package

When the font lives in a package rather than the application, pass the package name. The generated IconData constants then carryfontPackage, which is how Flutter resolves the asset from a dependency.

Keep the family entry in the package's ownpubspec.yaml equal to the configured font family, or Flutter will not find the glyphs at runtime.

Icons that genuinely need more than one alpha value

A single icon-font glyph stores one coverage mask, so it cannot hold two different opacities at once. Rather than silently flattening such an icon, GlyphPact can represent it as up to eight ordered solid-alpha outlines, each emitted into an auxiliary font family at the icon's unchanged codepoint.

Opt in per icon, in the config:

The generated Dart adds a layered widget and layer descriptors, and the plain IconData remains available as the fallback you explicitly chose:

The report records every layer's paint order, opacity, family, file, codepoint, and bounds. Seethe runnable layered example.

Check in a config instead of memorising flags

For anything you build more than once, a JSON config beats a shell command. Paths resolve relative to the config file, CLI flags override config values, and jobs: 0 selects up to eight bounded worker processes.

Per-icon entries are also where provenance goes.author, license, sourceUrl, andcopyright flow into the generatedATTRIBUTION.md, which also reports how many emitted icons have no declared provenance at all.

Use the report for a different generated shape

The built-in catalog is the standard Dart enumeration API. Report schema v3 is the stable lower-level input for another collection, order, variable name, or language. It records the font and Dart provider fields plus every emitted glyph's source, Dart name, codepoint, directionality, and layered metadata. It also recordscodepointsRemaining andrangeUtilization for allocation planning. The schema still validates historical v1 and v2 reports, but a custom generator must recognize v3 before upgrading to GlyphPact 1.1.

Check schemaVersion before generating. Report codepoints are 0x... strings. Parse them only in build-time generators and artifact tests; generated Dart should reference the reported provider constants instead of constructingIconData dynamically.

GlyphPact owns the entire configured output directory. Write custom generated files elsewhere, run that generator after GlyphPact, and give it its own non-rewriting drift check.

Make CI fail when the committed font goes stale

Generated artifacts drift. Someone edits an SVG and does not regenerate; someone regenerates and does not commit. Without a check, the repository quietly holds a font built from an older pack.

--check rebuilds a candidate set and compares it without rewriting the owned output. It may create the output's parent directory and leaves the sibling coordination file in place. With--json, inspect quality,policy, glyph counts, and typed issues rather than treating every zero exit as equivalent.

Large icon sets

One font holds at most 65,534 usable glyphs, an OpenType indexing limit GlyphPact enforces as a per-build ceiling. In practice the allocation range binds first: the default BMP private use area U+E000 - U+F8FF provides 6,400 lifetime slots, and tombstones consume them too because codepoints are never recycled.

Report schema v3 exposes codepointsRemaining andrangeUtilization. At or above 80% utilization, build and check emitCODEPOINT_RANGE_NEAR_EXHAUSTION while still succeeding, giving CI time to plan a new stable shard before allocation stops.

For a larger catalogue, allocate from a supplementary private use area with --start-codepoint 0xF0000, which provides 65,534 slots. Beyond that, split into several independently versioned fonts.

Compile time depends far more on SVG complexity than on file count, so GlyphPact publishes no private-corpus headline number. Thebenchmark guide provides a reproducible local runner for measuring your own pack instead.

The bulk SVG-to-Flutter guidecovers recursive discovery, CI, MCP automation, and the sharding plan for catalogues that cannot fit in one font.