Animated Markdown Renderer #

A production-ready Flutter package for animated markdown rendering with ChatGPT-style typing animation, supporting customizable animation speed, chunk size, multiple animation modes, and an extensible custom widget system.

Features #

✨ ChatGPT-style typing animation - Smooth, configurable typing effects
📡 Real-time streaming support - Stream markdown content as it arrives
🎨 Multiple animation modes - Character, word, token, or custom chunk-based
🎯 Preset configurations - Pre-configured styles matching popular AI assistants (ChatGPT, Claude, Grok, etc.)
🧩 Extensible custom widgets - Easy to add custom inline widgets with custom syntax patterns
📝 Full Markdown support - All standard markdown features
🎯 Inline widgets in lists - Custom widgets work seamlessly within list items
⚡ Performance optimized - Automatic throttling for large texts
🎛️ Fully configurable - Control speed, chunk size, and more

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  streaming_markdown:
    path: ../streaming_markdown  # or use pub.dev version when published

Quick Start #

import 'package:streaming_markdown/streaming_markdown.dart';

AnimatedMarkdown(
  markdown: '''
# Hello World
This is **animated** markdown with [[button:Click Me]] inline!

- List item with [[chip:Tag]] inline widget
- Another item with [[button:Action]] button
  - Nested list with [[chip:Nested]] chip
''',
  config: AnimationConfig(
    mode: AnimationMode.word,
    wordDelay: Duration(milliseconds: 50),
    chunkSize: 5,
  ),
  customBuilders: {
    'button': ButtonBuilder(),
    'chip': ChipBuilder(),
  },
)

Usage #

Basic Usage #

AnimatedMarkdown(
  markdown: '# Hello\nThis is animated markdown!',
)

Custom Animation Configuration #

AnimatedMarkdown(
  markdown: 'Your markdown here',
  config: AnimationConfig(
    mode: AnimationMode.character,  // or .word, .token, .custom
    charDelay: Duration(milliseconds: 15),
    wordDelay: Duration(milliseconds: 50),
    tokenDelay: Duration(milliseconds: 30),
    chunkSize: 1,  // For batch rendering
    throttleThreshold: 1000,  // Performance optimization
  ),
)

Streaming Content #

AnimatedMarkdown supports real-time streaming of markdown content via a Stream<String>. This is perfect for LLM responses, API streams, or any real-time content delivery. The widget automatically animates content as it arrives from the stream.

Basic Streaming:

Stream<String> markdownStream = getMarkdownStream();

AnimatedMarkdown(
  stream: markdownStream,
  config: AnimationConfig(
    mode: AnimationMode.token,  // Token mode is optimal for streaming
    tokenDelay: Duration(milliseconds: 30),
  ),
)

With Custom Builders:

AnimatedMarkdown(
  stream: markdownStream,
  config: AnimationConfig.chatGPT,
  customBuilders: {
    'button': ButtonBuilder(),
    'chip': ChipBuilder(),
  },
)

Creating a Stream:

Stream<String> createMarkdownStream() {
  final controller = StreamController<String>();
  
  // Simulate streaming chunks
  Future.microtask(() async {
    final chunks = ['# Hello\n', 'This is **streamed** ', 'content!\n'];
    for (final chunk in chunks) {
      await Future.delayed(Duration(milliseconds: 100));
      controller.add(chunk);
    }
    await controller.close();
  });
  
  return controller.stream;
}

The controller automatically handles stream completion and continues animating until all content is displayed. See the example/ directory for a complete streaming example.

Animation Modes #

Character Mode

Smooth, character-by-character animation:

AnimationConfig(
  mode: AnimationMode.character,
  charDelay: Duration(milliseconds: 15),
)

Word Mode

Faster, word-by-word animation (default):

AnimationConfig(
  mode: AnimationMode.word,
  wordDelay: Duration(milliseconds: 50),
)

Token Mode

Optimal for LLM streaming:

AnimationConfig(
  mode: AnimationMode.token,
  tokenDelay: Duration(milliseconds: 30),
)

Custom Mode

Configurable chunk-based rendering:

AnimationConfig(
  mode: AnimationMode.custom,
  chunkSize: 10,  // Characters per chunk
  charDelay: Duration(milliseconds: 20),
)

Preset Configurations #

AnimationConfig provides preset configurations that match popular AI assistant typing styles. These presets are optimized for different use cases:

ChatGPT Style: Character-based animation with smooth unit animations and slide effects:

AnimatedMarkdown(
  markdown: 'Your content',
  config: AnimationConfig.chatGPT,
)

Claude Style: Word-based animation with faster timing, optimized for quick responses:

AnimatedMarkdown(
  markdown: 'Your content',
  config: AnimationConfig.claude,
)

Grok Style: Fast token-based animation optimized for quick responses and real-time interactions:

AnimatedMarkdown(
  markdown: 'Your content',
  config: AnimationConfig.grok,
)

Perplexity Style: Fast word-based animation optimized for quick information delivery:

AnimatedMarkdown(
  markdown: 'Your content',
  config: AnimationConfig.perplexity,
)

Gemini Style: Moderate word-based animation with slightly slower pacing:

AnimatedMarkdown(
  markdown: 'Your content',
  config: AnimationConfig.gemini,
)

Copilot Style: Very fast token-based animation optimized for code generation and technical content:

AnimatedMarkdown(
  markdown: 'Your content',
  config: AnimationConfig.copilot,
)

All Available Presets:

AnimationConfig.chatGPT - Character mode with smooth animations
AnimationConfig.claude - Word mode with fast timing
AnimationConfig.grok - Token mode for quick responses
AnimationConfig.perplexity - Word mode for information delivery
AnimationConfig.gemini - Word mode with moderate pacing
AnimationConfig.copilot - Token mode for code generation

Custom Widgets #

Inline Widgets

Inline widgets work within text and list items:

Buttons:

AnimatedMarkdown(
  markdown: 'Click [[button:Click Me]] here',
  customBuilders: {
    'button': ButtonBuilder(
      onPressed: (label) => print('Button pressed: $label'),
    ),
  },
)

Chips:

AnimatedMarkdown(
  markdown: 'Tag: [[chip:Important]]',
  customBuilders: {
    'chip': ChipBuilder(
      onPressed: (label) => print('Chip pressed: $label'),
      color: Colors.blue,
    ),
  },
)

In List Items:

AnimatedMarkdown(
  markdown: '''
- Item with [[button:Action]] button
- Another with [[chip:Tag]] chip
  - Nested with [[button:Nested]] button
''',
  customBuilders: {
    'button': ButtonBuilder(),
    'chip': ChipBuilder(),
  },
)

Manual Control #

Control animation by setting autoStart: false and using a MarkdownTypingController directly:

final controller = MarkdownTypingController(
  fullText: 'Your text',
  config: AnimationConfig(mode: AnimationMode.word),
);

// Start animation
controller.start();

// Control animation
controller.pause();
controller.resume();
controller.stop();
controller.reset();
controller.jumpToEnd();

Creating Custom Builders #

The package provides a flexible builder system for creating custom markdown widgets. There are two base classes you can extend:

CustomMarkdownBuilder #

The base class for all custom builders. Use this when you need full control over widget building:

class MyCustomBuilder extends CustomMarkdownBuilder {
  @override
  Widget? buildWidget(md.Element element, TextStyle? style) {
    return Container(
      padding: EdgeInsets.all(4),
      decoration: BoxDecoration(
        color: Colors.blue.shade100,
        borderRadius: BorderRadius.circular(4),
      ),
      child: Text(element.textContent),
    );
  }
}

InlineBuilder #

Extend InlineBuilder for inline widgets that appear within text and list items. This is the recommended approach for most custom widgets:

class MyInlineBuilder extends InlineBuilder {
  @override
  Widget buildInline(md.Element element, TextStyle? style) {
    return Container(
      padding: EdgeInsets.all(4),
      child: Text(element.textContent),
    );
  }
}

Custom Syntax Patterns #

By default, custom builders use the pattern [[key:content]]. You can customize this pattern using the customSyntaxPatterns parameter:

AnimatedMarkdown(
  markdown: 'Citation [1] and [2] in text',
  customBuilders: {
    'citation': CitationBuilder(),
  },
  customSyntaxPatterns: {
    'citation': r'\[(\d+)\]',  // Custom regex pattern
  },
)

The custom pattern should include at least one capture group to extract the content. The first capture group will be used as the content.

Example: Citation Builder with Custom Pattern

class CitationBuilder extends InlineBuilder {
  final Function(String)? onPressed;
  
  CitationBuilder({this.onPressed});
  
  @override
  Widget buildInline(md.Element element, TextStyle? style) {
    return GestureDetector(
      onTap: () => onPressed?.call(element.textContent),
      child: Text(
        '[${element.textContent}]',
        style: style?.copyWith(
          color: Colors.blue,
          decoration: TextDecoration.underline,
        ),
      ),
    );
  }
}

// Usage with custom pattern
AnimatedMarkdown(
  markdown: 'This is content with citation [1] and [2].',
  customBuilders: {
    'citation': CitationBuilder(
      onPressed: (number) => print('Citation $number clicked'),
    ),
  },
  customSyntaxPatterns: {
    'citation': r'\[(\d+)\]',  // Matches [1], [2], etc.
  },
)

Custom Syntax (Advanced) #

For more complex syntax requirements, you can create a custom syntax parser:

class MyInlineSyntax extends CustomInlineSyntax {
  MyInlineSyntax() : super(RegExp(r'\[\[mywidget:(.*?)\]\]'));

  @override
  md.Node parseMatch(md.InlineParser parser, Match match) {
    final String content = match.group(1)?.trim() ?? '';
    return md.Element.text('mywidget', content);
  }
}

However, for most use cases, using customSyntaxPatterns with InlineBuilder is simpler and recommended.

Registering Builders #

AnimatedMarkdown(
  markdown: 'Content with [[mywidget:Custom Content]]',
  customBuilders: {
    'mywidget': MyInlineBuilder(),
  },
  customSyntaxPatterns: {
    'mywidget': r'\[\[mywidget:(.*?)\]\]',  // Optional custom pattern
  },
)

API Reference #