Streaming

Rendering a reply while the model is still generating it. Streaming in gpt_markdown is data, not a Stream — rebuild the widget with a longer string as tokens arrive, and say whether more is coming via isStreaming.

Accumulating text

Buffer incoming tokens in a StringBuffer, call setState on each chunk, and flip isStreaming to false on completion:

streaming_reply.dart

// Streaming is data, not a Dart Stream.
// Rebuild the widget with a longer string as tokens arrive.
class ReplyView extends StatefulWidget {
  const ReplyView({super.key, required this.stream});
  final Stream<String> stream;   // your transport layer

  @override
  State<ReplyView> createState() => _ReplyViewState();
}

class _ReplyViewState extends State<ReplyView> {
  final _buffer = StringBuffer();
  bool _generating = true;

  @override
  void initState() {
    super.initState();
    widget.stream.listen(
      (chunk) => setState(() => _buffer.write(chunk)),
      onDone:  () => setState(() => _generating = false),
      onError: (_) => setState(() => _generating = false), // always flip on error
    );
  }

  @override
  Widget build(BuildContext context) => SingleChildScrollView(
    padding: const EdgeInsets.all(16),
    child: GptMarkdown(
      _buffer.toString(),
      animation: GptMarkdownAnimation.fade,
      isStreaming: _generating,
    ),
  );
}

Animation modes

GptMarkdownAnimation.none is the default and costs nothing extra — no ticker, no wrapper widget. Use GptMarkdownAnimation.fade for a smooth reveal:

animation_modes.dart

// GptMarkdownAnimation.none  — the default.
// No ticker, no wrapper, no split: the tree is exactly what it was before
// the streaming feature existed. Use for history messages.
GptMarkdown(message.text)

// GptMarkdownAnimation.fade  — fade in newly revealed characters.
// The settled prefix is cached; only the live tail rebuilds.
GptMarkdown(
  message.text,
  animation: GptMarkdownAnimation.fade,
  isStreaming: message.isGenerating,
)

`isStreaming` lifecycle

Important: Without isStreaming the widget cannot tell whether the text got longer (new token) or replaced (regenerate). It also cannot know when to fast-forward the remaining reveal.

is_streaming.dart

// isStreaming tells the widget two things:
//   true  → more text is coming; keep the reveal animation running
//   false → the reply is complete; fast-forward any remaining reveal
//
// Without it the widget cannot distinguish:
//   • text got longer   → new token, continue revealing
//   • text got replaced → regenerate/branch, restart reveal
//
// Static history messages render with zero animation cost:
GptMarkdown(
  message.text,
  animation: GptMarkdownAnimation.fade,
  isStreaming: message.isGenerating,   // false for everything already sent
)

Advanced streaming behavior show performance and edge cases

Performance

The source text is split at the last safe blank line. The settled prefix is built once and cached behind a RepaintBoundary; only the live tail (at most one construct) rebuilds. Measured on a 7.7 kB reply, 120 appends:

Mode	Cost per token	Notes
animation: none	14.6 ms / token	Rebuilds whole document. Gets worse as reply grows.
animation: fade	11.0 ms / token	Settled prefix cached. Stayed flat in the measured reply.

The fade path is faster with the animation because the split avoided rebuilding the whole document in this benchmark. Results depend on source shape and device; treat these numbers as a measured example rather than a universal guarantee.

`charactersPerSecond` pacing

charactersPerSecond (default 300) is a baseline, not a cap. Pick the speed that reads well when the model is slower than the reveal — lag adaptation handles the opposite case automatically.

pacing.dart

// charactersPerSecond (default: 300) is the baseline reveal speed.
// Three behaviours layer on top of it automatically:
//
//  1. Lag adaptation — if the backlog would take > 0.4 s, the reveal
//     speeds up to clear it in that window. The animation never falls
//     further behind on a long reply.
//
//  2. Fast-forward — when isStreaming turns false, the remainder
//     lands within 0.15 s. A finished reply never trickles.
//
//  3. Restart — text that replaces rather than extends restarts the
//     reveal (regenerate or branch switch).
GptMarkdown(
  reply,
  animation: GptMarkdownAnimation.fade,
  isStreaming: generating,
  charactersPerSecond: 220,   // calmer default; adaptation still applies
)

Reduced motion

When MediaQuery.disableAnimations is true, the reveal is skipped and the finished document renders immediately. No ticker runs. Nothing to configure — but test it, because it is the path users with motion sensitivity get:

reduced_motion.dart

// The widget honours MediaQuery.disableAnimations.
// When true, the reveal is skipped and the document renders immediately.
// No ticker runs — the fast path is taken regardless of 'animation'.
//
// Test this path explicitly, because it is what users with motion
// sensitivity get in production:
MediaQuery(
  data: const MediaQueryData(disableAnimations: true),
  child: GptMarkdown(
    reply,
    animation: GptMarkdownAnimation.fade,
    isStreaming: generating,
  ),
)

Incomplete code fences

The split never cuts inside a fenced code block. An unterminated fence in the settled prefix would render as literal text until the closing fence arrived — a visible flicker. Use the closed flag in codeBuilder to show a lighter UI mid-stream:

incomplete_fence.dart

// While closed = false on a code block, the closing fence hasn't arrived.
// gpt_markdown never cuts the settled prefix inside a code fence —
// a split inside an unterminated fence would render as literal text
// and cause a visible flicker.
//
// Use the closed flag in codeBuilder to show a lighter UI mid-stream:
GptMarkdown(
  reply,
  animation: GptMarkdownAnimation.fade,
  isStreaming: generating,
  codeBuilder: (context, name, code, closed) {
    if (!closed) {
      return Container(
        width: double.infinity,
        padding: const EdgeInsets.all(12),
        color: Colors.grey.shade900,
        child: Text(
          code,
          style: const TextStyle(fontFamily: 'monospace', color: Colors.white70),
        ),
      );
    }
    return MyHighlightedCodeBlock(language: name, code: code);
  },
)

Fast-forward without visible animation

To get the split-document caching without a visible reveal, use a very high charactersPerSecond. The reveal finishes within a single frame while the prefix stays cached:

fast_forward.dart

// Set a very high charactersPerSecond to get the split-document caching
// without a visible reveal animation. The prefix stays cached while the
// reveal completes within a single frame.
//
// Useful when you want the performance benefit of the split but a
// 'no animation' appearance.
GptMarkdown(
  reply,
  animation: GptMarkdownAnimation.fade,
  isStreaming: generating,
  charactersPerSecond: 100000,   // finishes within one frame
)

Selection after reveal

The live tail is rebuilt every frame while revealing, so it is not a stable selection target. Selection returns the moment isStreaming becomes false and the fast-forward completes. History messages with isStreaming: false are fully selectable.

selection.dart

// Selection is unavailable on the live tail while the reveal runs.
// The tail is rebuilt every frame, so it is not a stable selection target.
// Selection returns the moment isStreaming becomes false and the
// fast-forward completes.
//
// Static history messages are fully selectable — wrap the whole chat in
// a single SelectionArea:
SelectionArea(
  child: ListView.builder(
    itemBuilder: (ctx, i) => GptMarkdown(
      messages[i].text,
      animation: GptMarkdownAnimation.fade,
      isStreaming: messages[i].isGenerating,
    ),
  ),
)

Chat list and scroll pitfalls

Rebuilding the whole chat list per token. The split keeps this widget cheap; it cannot help if the ListView above rebuilds every bubble. Make the generating message itself listenable so only that bubble rebuilds.

Jumping the scroll position on every token. The reply grows continuously — animating to the bottom on each token fights the reveal. Animate to the extent, or only pin-scroll while the user is already at the bottom.

Leaving isStreaming: true after the reply finishes. The ticker keeps running and the tail keeps rebuilding for nothing. Always flip it in onDone — including error paths.

chat_list.dart

// The split keeps *this widget* cheap. It cannot help if the parent
// ListView rebuilds every bubble on each token.
//
// Make only the generating message listenable:
class _ChatListState extends State<ChatList> {
  // Only _messages[_generatingIndex] changes during streaming —
  // use a ValueNotifier or Riverpod so the rest of the list stays stable.
  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: _messages.length,
      itemBuilder: (ctx, i) {
        final msg = _messages[i];
        return GptMarkdown(
          msg.text,
          animation: GptMarkdownAnimation.fade,
          isStreaming: msg.isGenerating,
        );
      },
    );
  }
}

// Auto-scrolling pitfall:
// The reply grows continuously — jumping to the bottom on every token
// fights the reveal animation. Instead, animate to the extent, or
// only pin-scroll while the user is already at the bottom.

← Code Blocks Themes