repository·main·Indexed 41 days ago
https://github.com/infinitix-llc/gpt_markdownA production-grade Flutter renderer for AI-generated content. It supports complex Markdown, LaTeX math, streaming text updates, and custom inline UI patterns. The package provides high-performance rendering for AI chat interfaces, featuring split-document caching for streaming responses and a flexible customization system using Style objects for appearance and Builders for structural changes.
gpt_markdown is a Flutter package designed specifically for rendering Markdown and LaTeX content generated by AI models. It is optimized for AI chat interfaces, supporting streaming responses and rich AI-specific outputs.You can customize gpt_markdown using two distinct mechanisms that do not overlap:
Every component (headings, links, code blocks, etc.) supports both styles and builders.
// Example: Using a Style object for appearance
GptMarkdown(
text,
styleSheet: const GptMarkdownStyleSheet(
blockQuote: BlockQuoteStyle(barWidth: 4),
),
)
// Example: Using a Builder for structure
GptMarkdown(
text,
blockQuoteBuilder: (context, content, style) => Card(
child: content,
),
)Markdown is hierarchical. InlinePattern allows you to restrict where a pattern is applied using scopes to prevent rendering bugs and unintended matches.
content: Ordinary document and inline text.linkLabel: Inside the label of a [label](url) link.tableCell: Inside a table cell.heading: Inside a # heading.By default, InlinePattern uses MarkdownComponent.allScopesExceptLinkLabel.
Do not return a WidgetSpan inside a linkLabel scope. On iOS, returning a WidgetSpan inside a link label (which is already wrapped in a WidgetSpan) creates a nested placeholder that is invisible. If your pattern needs to work inside link labels, ensure your builder returns a TextSpan.
// Safe for nesting in link labels
InlinePattern(
pattern: RegExp(r'GH-\d+'),
builder: (context, match, style) => TextSpan(text: match.group(0)!),
scopes: MarkdownComponent.allScopes,
)
// Restricted to prose only
InlinePattern(
pattern: RegExp(r'#token'),
builder: (context, match, style) => TextSpan(text: match.group(0)!),
scopes: const {MarkdownScope.content},
)MediaQuery.disableAnimationsOf is true, the reveal is skipped and the document renders immediately without a ticker.When providing components (for blocks) or inlineComponents (for inline syntax) to GptMarkdown, providing a list replaces the default behavior. To keep built-in support (like bold, links, and tables), you must spread the default components into your list.
Order matters: The list order determines which regex matches first and which handler claims the match. To override a default component, prepend your custom component to the list.
Performance tip: Component lists are compared by identity. Do not build the list inside a build method; instead, cache it as a late final variable to avoid regenerating spans every frame.
// Correct way to add a custom component while preserving defaults
GptMarkdown(
text,
components: [...],
inlineComponents: [MyComponent(), ...MarkdownComponent.inlineComponents],
)The isStreaming boolean is required for correct behavior:
isStreaming: true: The widget uses an optimized 'split' path. It caches the 'settled prefix' (everything before the last safe blank line) and only rebuilds the 'live tail'. This makes streaming much faster than static rendering for long documents.isStreaming: false: The widget renders statically. Use this for history messages or once a stream has completed. This avoids all animation and ticker overhead.Warning: Always set isStreaming to false when the stream finishes or encounters an error. Leaving it true causes the ticker to run indefinitely, wasting resources.
GptMarkdown(
message.text,
animation: GptMarkdownAnimation.fade,
isStreaming: message.isGenerating, // false for history or finished messages
)When customizing the rendering, you must choose between two distinct mechanisms that do not overlap. Using the wrong one can lead to unnecessary complexity or loss of default functionality.
Best Practice: If you only want to change a color or a font, use a Style object. Using a Builder for simple visual changes causes the component to lose its default structure and any future improvements made to that component's default implementation.
// Example of using a Style object for appearance
BlockQuoteStyle(barWidth: 4)
// Example of using a Builder for structural replacement
blockQuoteBuilder: (context, content) => MyCustomWidget(content)To allow users to select and copy text, wrap the GptMarkdown widget in a SelectionArea.
For RTL languages, use the textDirection property. GptMarkdown correctly handles the visual ordering of inline widgets (math, images, links) in mixed-direction paragraphs.
// Enable selection
SelectionArea(child: GptMarkdown(reply))
// Enable RTL
GptMarkdown(reply, textDirection: TextDirection.rtl)Use the GptMarkdown widget to render AI-generated markdown.
Important: The widget sizes itself to its content and does not scroll. To prevent long replies from overflowing, wrap the widget in a scrollable container like SingleChildScrollView or use it within a ListView.builder.
// Basic usage
GptMarkdown('# Hello\n\nSome **bold** text and `inline code`.')
// Recommended: Wrap in a scrollable widget to prevent overflow
SingleChildScrollView(
padding: const EdgeInsets.all(16),
child: GptMarkdown(reply),
)
// Usage in a chat list
ListView.builder(
itemCount: messages.length,
itemBuilder: (context, i) => Padding(
padding: const EdgeInsets.symmetric(vertical: 8),
child: GptMarkdown(messages[i].text),
),
)In v1.2.0, text scaling is now proportional and exact. If you are building custom inline widgets using WidgetSpan, ensure they do not scale twice by wrapping the child in MediaQuery.withNoTextScaling.
WidgetSpan(child: MediaQuery.withNoTextScaling(child: MyChip()))The widgetbook provides a toolbar to test how components respond to various environmental factors. Available addons include:
GptMarkdownThemeData).Additionally, some use cases include custom knobs (e.g., sliders for font size factor, border width, radius, and padding).
If you want the performance benefits of the 'split' path (caching the prefix) but do not want a visible reveal animation, do not use animation: none. Using none forces the widget to rebuild the entire document on every token.
Instead, use GptMarkdownAnimation.fade with a very high charactersPerSecond value. This allows the reveal to complete within a single frame while still utilizing the optimized split path.
GptMarkdown(
reply,
animation: GptMarkdownAnimation.fade,
isStreaming: generating,
charactersPerSecond: 100000, // Completes within a frame
)