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

Character reveal supports none, typewriter, fade, blurIn, and wave. The default none mode renders immediately with no ticker or reveal wrapper:

animation_modes.dart

// Character reveal modes:
// none       — immediate output; no ticker or reveal wrapper
// typewriter — paced characters with no per-character visual transition
// fade       — arriving text fades from transparent
// blurIn     — arriving text resolves from blur while fading in
// wave       — an accent-colour crest travels across the newest characters
GptMarkdown(
  message.text,
  animation: GptMarkdownAnimation.blurIn,
  isStreaming: message.isGenerating,
  charactersPerSecond: 300,
  revealFadeSeconds: 0.25,
)

`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
)

Block entrances and lazy rendering

In 1.3, character reveal and block entrance animation are separate. blockAnimation applies to atomic blocks such as headings, lists, tables, and code fences. GptMarkdownremains eager; use SliverGptMarkdown inside a CustomScrollView when offscreen blocks should wait for the viewport.

block_animation.dart

// Character reveal and block entrance are independent.
GptMarkdown(
  reply,
  animation: GptMarkdownAnimation.fade,
  blockAnimation: GptMarkdownBlockAnimation.growIn,
  blockAnimationDuration: const Duration(milliseconds: 200),
  blockAnimationCurve: Curves.easeOut,
  isStreaming: generating,
)

// Options: none, fadeIn, growIn, slideUp, and scaleIn.
// For a viewport-lazy message list, use the sliver explicitly:
CustomScrollView(
  slivers: [
    SliverGptMarkdown(reply),
  ],
)

SliverGptMarkdown for long documents

Use SliverGptMarkdown in CustomScrollView.slivers when a long document has its own scrollable viewport. Segmentation and custom syntax boundary matching happen eagerly, but built-in AST, span, and widget construction waits for the viewport and its cache extent. The widget has no scroll controller and composes with other slivers.

sliver_markdown.dart

SelectionArea(
  child: CustomScrollView(
    slivers: [
      const SliverAppBar(title: Text('Answer')),
      SliverGptMarkdown(
        document,
        config: const GptMarkdownConfig(
          style: TextStyle(fontSize: 16),
        ),
      ),
    ],
  ),
)

// Source updates appear immediately. Character reveal is intentionally
// available on GptMarkdown, not SliverGptMarkdown.

Selection covers mounted content only. Offscreen segments may be disposed and rebuilt.

One very large paragraph, list, table, or fence is still one segment; rows and lines are not virtualized internally.

Deprecated components or inlineComponents force one SliverToBoxAdapter, preserving legacy whole-document behavior but disabling viewport laziness.

Low-level StreamingMarkdown widget show

Most apps should configure streaming directly on GptMarkdown. The exported StreamingMarkdown widget is the lower-level split-and-cache layer for an integration that supplies its own Markdown renderer. Its builder renders both the settled prefix and live tail; seamGap supplies the block spacing between them.

custom_streaming_renderer.dart

StreamingMarkdown(
  text: reply,
  isStreaming: generating,
  charactersPerSecond: 300,
  seamGap: 16,
  builder: (context, slice) => MyMarkdownRenderer(slice),
)

Advanced streaming behavior show performance and edge cases

Performance

The modern parser normalizes the source and re-splits only the previous tail plus newly appended text. Pure-Dart document structure is cached separately from styled spans, and reveal work is limited to segments intersecting the active tail. This keeps frequent updates proportional to the changed region in the common case:

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.

Results depend on source shape and device. The branch documentation reports rendering-work measurements rather than FPS or response latency; mobile, web, selection, RTL, and full scroll-through behavior need separate profiling.

`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. revealFadeSeconds defaults to 0.25 and controls how long an arriving character takes to settle; it does not affect typewriter. Block entrances default to 200 milliseconds with Curves.easeOut.

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.disableAnimationsOf(context) 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 checks MediaQuery.disableAnimationsOf(context).
// 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,
    ),
  ),
)

Streaming semantics

While a live reply is rebuilding, accessibility semantics collapse to one stable node so assistive technology is not presented with a changing tree on every token. Structured semantics reopen after the reply becomes quiet and reveal completion settles. Assert the final structure only after setting isStreaming: false and pumping through the quiet period.

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.

Run the streaming demo

The package example includes a simulated reply with independent model-speed and reveal-speed sliders. Set the model faster than the reveal to watch lag adaptation catch up, press Stop mid-reply to see fast-forward, and switch to none to compare the non-animation path.

terminal

cd example
flutter run -d macos -t lib/streaming_demo.dart

← Code Blocks Themes