Text

Text deserves its own motion vocabulary. A heading that types itself out, a hero title where each word drops in a beat after the last, a gradient that sweeps endlessly across a label — these are common enough patterns that nib_motion ships four purpose-built widgets for them instead of asking you to hand-roll per-character animation on top of NibMotion yourself.

NibText (with NibTextConfig) handles per-character, per-word, or per-line staggered entrances and exits. NibGradientText sweeps an animated gradient across static text. NibTextReveal wipes a block of text into view with a clip mask. NibTypewriter reveals text one character at a time, optionally with a blinking cursor. Each is independent — pick whichever matches the effect you’re after.

NibText: staggered character, word, and line animation

NibText splits its string into units — characters, words, or lines, depending on NibTextConfig.unit — and wraps each animated unit in its own NibMotion, staggered in by NibTextConfig.staggerDelay. It reuses the same zero-setState NibMotion engine the rest of the package is built on; the splitting and staggering logic is the only thing NibText adds.

import 'package:flutter/material.dart';
import 'package:nib_motion/nib_motion.dart';
 
class FadeInHeadline extends StatelessWidget {
  const FadeInHeadline({super.key});
 
  @override
  Widget build(BuildContext context) {
    return NibText(
      'Build interfaces that move.',
      style: Theme.of(context).textTheme.headlineMedium,
      config: const NibTextConfig(
        unit: NibTextUnit.word,
        initial: NibAnim(opacity: 0, y: 12),
        animate: NibAnim(opacity: 1, y: 0),
        staggerDelay: Duration(milliseconds: 40),
      ),
    );
  }
}

Each word fades and slides up into place, one staggerDelay after the previous word started. Whitespace runs between words are preserved as plain, unanimated Text so the layout reads naturally — only the words themselves are wrapped in NibMotion.

Choosing a unit

NibTextConfig.unit is a NibTextUnit: character (the default), word, or line. character splits on grapheme clusters rather than raw UTF-16 code units, so multi-code-point emoji and combining marks stay intact as a single animated piece. line splits on \n and lays the result out in a Column instead of a Wrap — useful for a multi-line headline where each line arrives as a whole.

NibText(
  'One line at a time.\nThen the next.',
  config: const NibTextConfig(
    unit: NibTextUnit.line,
    initial: NibAnim(opacity: 0, x: -16),
    animate: NibAnim(opacity: 1, x: 0),
    staggerDelay: Duration(milliseconds: 120),
  ),
)

staggerFrom: where the delay accumulates from

NibTextConfig.staggerFrom (a NibTextStaggerFrom) controls the order units animate in, independent of the order they’re laid out in:

NibText(
  'CENTER OUT',
  config: const NibTextConfig(
    unit: NibTextUnit.character,
    initial: NibAnim(opacity: 0, scale: 0.5),
    animate: NibAnim(opacity: 1, scale: 1),
    staggerDelay: Duration(milliseconds: 25),
    staggerFrom: NibTextStaggerFrom.center,
  ),
)

Exit animations

Setting NibTextConfig.exit wraps each animated unit in its own NibPresence, so removing the NibText from the tree (inside an ancestor NibPresence) plays every unit’s exit animation before it actually unmounts — the same per-unit stagger applies on the way out as on the way in.

NibText(
  'Saved!',
  config: const NibTextConfig(
    unit: NibTextUnit.character,
    initial: NibAnim(opacity: 0),
    animate: NibAnim(opacity: 1),
    exit: NibAnim(opacity: 0, y: -8),
    staggerDelay: Duration(milliseconds: 20),
  ),
)

NibText.rich

NibText.rich takes an InlineSpan (such as a TextSpan tree) instead of a flat String — its toPlainText() is split into units the same way, with style used as the shared base style for every unit. Per-span styling inside the original InlineSpan is not preserved per unit.

NibGradientText: a sweeping gradient across static text

NibGradientText paints text once, then sweeps an animated Gradient across it by masking the gradient onto the rendered glyphs. The text itself never moves — only the gradient’s position animates — which makes this a cheap way to add a shimmer or shine effect to a label or heading.

import 'package:flutter/material.dart';
import 'package:nib_motion/nib_motion.dart';
 
class ShimmeringTitle extends StatelessWidget {
  const ShimmeringTitle({super.key});
 
  @override
  Widget build(BuildContext context) {
    return NibGradientText(
      'Premium',
      style: Theme.of(context).textTheme.headlineSmall,
      gradient: const LinearGradient(
        colors: [Color(0xFF54C5F8), Color(0xFF02569B), Color(0xFF54C5F8)],
      ),
      duration: const Duration(milliseconds: 2200),
    );
  }
}

By default the sweep loops forever (repeat: true), travelling left to right and wrapping back to the opposite edge each cycle. Set repeat: false to play the sweep once and stop, or direction: TextDirection.rtl to reverse it. style’s color is ignored — the gradient is what tints the glyphs, via a BlendMode.srcIn mask applied to the painted text.

NibTextReveal: a clip-mask wipe

NibTextReveal reveals its child — typically a block of text, but any widget works — by animating a clip mask that wipes in from one edge. Unlike NibText, there’s no per-character splitting: the whole block reveals at once, as if a panel were sliding away to expose it.

import 'package:flutter/material.dart';
import 'package:nib_motion/nib_motion.dart';
 
class WipeInTitle extends StatelessWidget {
  const WipeInTitle({super.key});
 
  @override
  Widget build(BuildContext context) {
    return NibTextReveal(
      direction: NibTextRevealDirection.left,
      duration: const Duration(milliseconds: 600),
      curve: Curves.easeOutCubic,
      child: Text(
        'Welcome back',
        style: Theme.of(context).textTheme.headlineMedium,
      ),
    );
  }
}

direction (a NibTextRevealDirection) is one of left, right, up, or down, describing the edge the reveal wipes in from — left clips the content starting at its left edge and grows rightward until it’s fully visible. Pair delay with a controller (NibMotionController) and call controller.start() to replay the wipe on demand, such as when a card scrolls into view.

NibTextReveal(
  direction: NibTextRevealDirection.up,
  delay: const Duration(milliseconds: 200),
  duration: const Duration(milliseconds: 500),
  child: const Text('Now appearing from below'),
)

NibTypewriter: classic character-by-character reveal

NibTypewriter reveals text one grapheme at a time at a fixed speed, optionally with a blinking cursor. This is the one text widget in nib_motion that uses setState internally rather than a MotionValue — the revealed character count is a discrete, content-level value advanced by a timer, not a continuous per-frame paint value, so there’s no animation machinery to bypass.

import 'package:flutter/material.dart';
import 'package:nib_motion/nib_motion.dart';
 
class TerminalGreeting extends StatelessWidget {
  const TerminalGreeting({super.key});
 
  @override
  Widget build(BuildContext context) {
    return NibTypewriter(
      'Initializing system...',
      speed: const Duration(milliseconds: 45),
      cursor: '_',
      style: const TextStyle(fontFamily: 'monospace', fontSize: 16),
      onComplete: () => debugPrint('typing finished'),
    );
  }
}

Set repeat: true to loop forever — once typing finishes, NibTypewriter pauses briefly, deletes the text at deleteSpeed (or speed if unset), and types it again:

NibTypewriter(
  'Looping forever...',
  speed: const Duration(milliseconds: 60),
  deleteSpeed: const Duration(milliseconds: 30),
  repeat: true,
  cursor: '|',
)

delay defers the start of typing — useful for sequencing a typewriter effect after some other entrance animation has finished. onComplete fires exactly once, the first time the full text is revealed, even across later repeat cycles.

API reference

NibText

NibTextConfig

NibTextUnit

NibTextStaggerFrom

NibGradientText

NibTextReveal

NibTextRevealDirection

NibTypewriter

Next steps

• Animate — NibText’s per-unit entrances are built on the same NibAnim/NibTransition model that drives every other NibMotion in the package.
• Lists and stagger — NibText’s staggerDelay/staggerFrom mirror the stagger config used for animating lists of widgets, if you want the same timing language in both places.
• Transitions — for the curve/spring options available to NibTextConfig.transition and NibTextReveal.curve.