In Flutter, how do you ship custom brand icons as an icon font, and why must each IconData for that font be const?

## Why a custom icon font A pet-clinic app has brand icons that no stock set contains: a paw with a heart, a syringe with a drop, a carrier crate. They are single-colour line drawings, which is exactly what an icon font is good at: every glyph scales cleanly, takes its colour from `IconTheme`, and the whole set costs one file. (Multi-colour marks belong in SVG instead.) ## Building and declaring the font 1. Export each icon as an SVG on the same canvas size. 2. Merge them into one `.ttf` with an icon-font generator, which assigns each glyph a code point in the Unicode private-use area and usually emits a code-point map. 3. Declare the font like any custom family: ```yaml flutter: fonts: - family: ClinicIcons fonts: - asset: fonts/ClinicIcons.ttf ``` 4. Expose each glyph as a constant: ```dart @staticIconProvider abstract final class ClinicIcons { static const String _family = 'ClinicIcons'; static const IconData pawHeart = IconData(0xe800, fontFamily: _family); static const IconData syringe = IconData(0xe801, fontFamily: _family); } ``` - **`fontFamily`** must equal the pubspec `family`. - **`fontPackage`** is required when the font is declared in a package, so `Icon` can resolve the namespaced family. - **`matchTextDirection: true`** makes `Icon` mirror a directional glyph in right-to-left locales. - **`@staticIconProvider`** marks a class that holds only `static const` icons, so the tree shaker can treat the declarations themselves as not being uses. ## Why every IconData must be const Release builds of Android, iOS, web and the other targets run the **icon tree shaker** by default (`--tree-shake-icons` is on; debug builds ignore it). The `flutter` tool asks a constant finder for every `IconData` instance in the compiled program, reads their code points, and subsets each icon font to those glyphs. The mechanism only works if every use is **known at compile time**: - A `const IconData(...)` is visible to the finder, with its code point. - `IconData(json['icon'] as int, fontFamily: 'ClinicIcons')` is not. The tool cannot know which glyphs it may need, so it stops with `This application cannot tree shake icons fonts. It has non-constant instances of IconData at the following locations:` and suggests building again with `--no-tree-shake-icons`. The fix is almost always to map dynamic keys to constants instead of constructing code points: ```dart IconData iconForVisit(String type) => switch (type) { 'vaccination' => ClinicIcons.syringe, _ => ClinicIcons.pawHeart, }; ``` Opting out with `--no-tree-shake-icons` works but ships every glyph of every icon font; how much that costs is an app-size question. ## Keeping code points stable The code point is the contract between the font file and the Dart constants. If a designer adds an icon and the generator renumbers the glyphs, `ClinicIcons.syringe` may silently draw the carrier crate instead — no compile error, no runtime error. Protect the mapping: - Commit the generator's code-point map next to the font and review changes to it like code. - Generate the Dart class from that map rather than editing constants by hand. - Append new glyphs at new code points; never reuse a retired one. - Keep a screenshot or golden check of an icon sheet so a swapped glyph is visible in review. ## What changed in Flutter 3.44 | Before 3.44 | Since 3.44 | |---|---| | `IconData` could be extended or implemented | `IconData` is a `final class` | | `enum AppIcons implements IconData` was a common pattern | that enum no longer compiles | | non-const arguments compiled silently | `codePoint`, `fontFamily` and `fontPackage` are `@mustBeConst`; the analyzer reports `non_const_argument_for_const_parameter` | The migration guide replaces the enum with a wrapper class holding `static const` instances and a small widget that renders `Icon(icon.iconData)`, keeping dot shorthands where the type can be inferred. If a truly dynamic icon is unavoidable, add `// ignore: non_const_argument_for_const_parameter` and accept that the build needs `--no-tree-shake-icons`. ## Checklist 1. One font per icon set, declared once. 2. Every glyph a `static const IconData` in an `@staticIconProvider` class. 3. Server- or database-driven icons mapped to constants, never built from integers. 4. Directional glyphs marked with `matchTextDirection: true`.