text_morph_flutter #

Shape-level text morphing for Flutter: instead of cross-fading, Morph animates one string's glyph outlines into another's (or into an arbitrary vector shape), built on top of glyph_path and glyph_path_flutter.

Demos #

Two things to notice across the demos below: glyphs morph as vector outlines instead of cross-fading, and the same engine drives text→text, text→shape, and shape→shape alike.

Text ↔ shape #

The clearest look at what sets this apart from a typical text transition.

Word → icon — text morphing into a multi-contour shape with a hole, via ShapeSource.fromPath.

App logo reveal — a shape-cloud burst settling into a large ShapeSource mark. A template for a splash screen or empty-state flourish.

Everyday UI states #

Drop-in replacements for interactions you're already building.

Getting oriented #

Onboarding walkthrough — start here to see multi-line TextSource, textAlign, and color morph working together before diving into the API.

All seven demos live in example/ — see Running the example app to try them yourself.

Installation #

flutter pub add text_morph_flutter

Or add to pubspec.yaml manually:

dependencies:
  text_morph_flutter: ^1.0.0

Morph renders text via a glyph_path Font, so most apps also want glyph_path directly (to parse font bytes into a Font) — flutter pub add glyph_path if it isn't already a dependency.

Quick start #

import 'package:flutter/material.dart';
import 'package:glyph_path/glyph_path.dart';
import 'package:text_morph_flutter/text_morph_flutter.dart';

class Example extends StatefulWidget {
  const Example({super.key, required this.font});
  final Font font;

  @override
  State<Example> createState() => _ExampleState();
}

class _ExampleState extends State<Example> {
  String _text = 'Hello';

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () => setState(() => _text = _text == 'Hello' ? 'World' : 'Hello'),
      child: SizedBox(
        width: 300,
        height: 120,
        child: Morph(
          font: widget.font,
          target: TextSource(font: widget.font, text: _text),
          fontSize: 64,
        ),
      ),
    );
  }
}

font is a glyph_path Font — parse one once (e.g. from a loaded font asset's bytes via Font.parse) and reuse it; see glyph_path's own docs for details on loading fonts.

Changing target (here, via setState) triggers the morph animation automatically — Morph diffs the new target against what's currently displayed and animates between them.

Key concepts #

• MorphSource — a morph endpoint. target (and, implicitly, whatever was displayed before it) is one. Two implementations ship today:
  • TextSource — renders a string in a Font. text may contain explicit \n line breaks, and maxWidth additionally word-wraps against a fixed width — both flow through the same per-glyph alignment/ stagger/caching pipeline as single-line text. rtlScript opts a pure, non-cursive right-to-left string (e.g. Hebrew) into mirrored glyph order and punctuation — see Known limitations for exactly what it does and doesn't cover.
  • ShapeSource — renders an arbitrary vector shape (a list of glyph_path Contours, e.g. parsed from SVG path data or built by hand) fitted to the surrounding text's size. target can switch between TextSource and ShapeSource freely — morphing text into a shape and back uses the exact same mechanism as morphing text into different text. ShapeSource.fromPath builds one directly from a dart:ui Path instead, sampling it via PathMetric since Path doesn't expose the drawing commands it was built from.
• MorphOptions — tuning knobs layered under MorphStyle and stagger; every field defaults to a value that reproduces the look as if the option didn't exist. See MorphOptions reference below for what each one does.
• TextMorph / PathMorph — the lower-level, widget-free geometry engine Morph is built on, exported for callers who want to drive their own CustomPainter instead of using the widget directly.
• Morph.textAlign — horizontal alignment (left/right/center; start/end resolve against the ambient Directionality, and justify falls back to start, matching how Text itself treats a single/last line). For multi-line TextSource content, the same value also controls how the lines align relative to each other, so a paragraph's internal alignment always matches how the whole block is placed in the box.
• MorphCache — an opt-in, cacherine-backed cache for PathMorph's most expensive per-transition work (contour pairing/alignment). Pass one instance to Morph.cache (or TextMorph.between's cache parameter) when your content replays the same glyph-pair transitions often — a dashboard numeric ticker (the same digit-to-digit transitions recur every tick) or a search-suggestion list (the same candidate substrings recur as a query is edited back and forth) are the two cases it's aimed at. Construct and reuse one instance the same way you reuse a Font. null (the default) never caches.

MorphOptions reference #

Two enums it builds on, first:

• MorphStyle — shape (always morph outlines, the default look), crossFade (never morph outlines; fade in place instead), or auto (shape-morph glyph pairs similar enough per the two thresholds below, cross-fade the rest).
• GlyphAlignment (MorphOptions.alignment) — how glyphs from the two strings are paired when they don't correspond one-to-one: byIndex pairs purely by position; diff (the default) minimizes pop-in/out glyphs and prefers keeping identical characters in place; wholePath skips per-glyph pairing entirely and matches the two strings' contours as one pool by area rank — useful for text↔complex-shape morphs (see the "word → icon" demo above), at the cost of stagger having no effect.

API Reference #

Running the example app #

cd example
flutter run -d macos   # or chrome, ios, etc.

main.dart's app bar links out to every demo shown above, plus a free-form playground (presets, alignment modes, idle pulse/wobble sliders, shape morphing).

Known limitations #

• LTR text order only, plus opt-in mirroring for pure RTL scripts. Glyph order follows the font's left-to-right advance widths by default. TextSource.rtlScript reverses glyph order and swaps paired punctuation (()/[]/{}/<>/«»/‹›) for a line — correct for a pure, non-cursive RTL script like Hebrew — and TextSource.embedLtr lets a substring (e.g. a Latin brand name) keep its own glyph order within an RTL line, though the caller must mark it manually (no automatic script detection, no nesting). This isn't full Unicode Bidi (UAX #9) reordering or contextual shaping, so cursive/joining scripts like Arabic, Farsi, or Urdu — which need each letter substituted with its own initial/medial/ final/isolated form — aren't supported.

• Accessibility. Morph exposes its current target's text as a Semantics label (or an explicit semanticLabel for a ShapeSource), respects the ambient MediaQuery.textScaler, and honors MediaQuery.disableAnimations ("reduce motion") by completing a transition in a single frame. An opt-in announceChanges flag sets Semantics.liveRegion for content that changes off-focus. The highContrastColor/highContrastStrokeColor/highContrastStrokeWidth fields, when set, replace color/strokeColor/strokeWidth while MediaQuery.highContrast is on; they default to null since Morph has no way to judge a given color's contrast on its own.

• Performance scales with contour/vertex count. An actively transitioning contour re-runs its cubic lerp, winding computation, and path-boolean compositing from scratch every frame — fine for the short strings and moderate shape complexity typical UI morphs involve, but a very long wholePath string or high-vertex ShapeSource has no incremental-update path for whatever is genuinely mid-transition. Settled endpoints (a glyph done with its stagger window, a contour pair settled at 0/1) are cached and reused instead of recomposited each frame, and a PathMorph's one-time construction cost can itself be cached across repeated transitions via MorphCache. A few internal ceilings also bound the worst case for inputs well past typical use, falling back to a cheaper approximation once exceeded:

  Ceiling	Bound	Fallback once exceeded
  TextSource UTF-16 code units laid out	4096	Excess characters (and any dangling surrogate/combining mark at the cut point) are dropped rather than laid out.
  Glyphs per side, per-glyph slot alignment (stagger/GlyphAlignment.byIndex/.diff)	2000	Falls back to GlyphAlignment.wholePath instead of building per-glyph slots.
  Glyphs per side, GlyphAlignment.diff	400	Skips the O(n·m) edit-distance alignment and pairs by index (byIndex) instead.
  Contours per pool, hole classification	300	Skips the O(n²) nesting test; every contour in the pool is treated as solid.
  Contours per role group, proximity match	200	Skips the O(m·n) cost-matrix search and pairs purely by area rank instead.
  Matched pairs per role group	2000	Excess contours (however many more a pool has) fall back to the same cheap grow/shrink-from-centroid treatment an outright from/to count mismatch already gets, instead of each paying full per-pair alignment and silhouette-dissimilarity cost — the two ceilings above only cheapen how a large pool is searched, not how many pairs a search of it produces.
  Vertices per contour	2000, shrinking (to a floor of 8) as contour count on either side rises past 200	Decimates the contour to a lower-fidelity, straight-segment version with the same winding. Scaling the per-contour cap down keeps total alignment cost (pool size × cap²) bounded even for a pool with many high-vertex contours, which the count-based ceilings above don't limit on their own.
  Sampled vertices per sub-path, ShapeSource.fromPath	2000	Widens the effective sample spacing past what was requested, instead of letting vertex count grow further.
  Sub-paths sampled, ShapeSource.fromPath	500	Drops remaining sub-paths instead of letting total sampled vertices grow without limit.

See CHANGELOG.md for the full history of features and fixes.

Contributing #

After cloning, flutter pub get sets up all dependencies, including the example app's own (cd example && flutter pub get).

# 1. Format the code
dart format lib test example

# 2. Run static analysis
flutter analyze --fatal-infos

# 3. Run the test suite (with coverage)
flutter test --coverage

This mirrors what CI (.github/workflows/ci.yml) checks on every pull request. Feel free to open an issue or submit a pull request for any suggestions or bug fixes.

License #

BSD 3-Clause — see LICENSE.

Dependencies #

flutter_test is a dev-only dependency (bundled with the Flutter SDK) and is not included in the published package.