API Reference
Use the basic guide first. This page is the lookup sheet for parameters, builders, and advanced customization.
The three things you usually need
Looks?
Use styleSheet.
Different widget?
Use a component builder.
App-specific token?
Use inlinePatterns.
Full constructor signature show
gpt_markdown.dart
1const GptMarkdown(
2 this.data, { // required positional String
3 super.key,
4
5 // ── Text ───────────────────────────────────────────
6 this.style, // TextStyle?
7 this.textDirection = TextDirection.ltr,
8 this.textAlign, // TextAlign?
9 this.textScaler, // TextScaler?
10 this.maxLines, // int?
11 this.overflow, // TextOverflow?
12
13 // ── Appearance ─────────────────────────────────────
14 this.styleSheet, // GptMarkdownStyleSheet? — 12 per-component styles
15 this.inlineCodeStyle, // InlineCodeStyle? — inline code only
16
17 // ── Links ──────────────────────────────────────────
18 this.followLinkColor = false,
19 this.onLinkTap, // void Function(String url, String title)?
20 this.inlineLinkBuilder, // InlineLinkBuilder?
21 ('Use inlineLinkBuilder. Will be removed in 2.0.0.')
22 this.linkBuilder, // LinkBuilder?
23
24 // ── Autolinks ──────────────────────────────────────
25 this.autolink = true,
26 this.autolinkSchemes = const <String>{},
27
28 // ── LaTeX ──────────────────────────────────────────
29 this.useDollarSignsForLatex = false,
30 this.latexWorkaround, // String Function(String tex)?
31 this.latexBuilder, // LatexBuilder?
32
33 // ── Code blocks ────────────────────────────────────
34 this.codeBuilder, // CodeBlockBuilder?
35 this.onCodeCopy, // void Function(String code)?
36
37 // ── Inline code ────────────────────────────────────
38 this.inlineCodeBuilder, // InlineCodeBuilder? — returns InlineSpan, not Widget
39 ('Use inlineCodeBuilder. Will be removed in 2.0.0.')
40 this.highlightBuilder, // HighlightBuilder? — returns Widget
41
42 // ── Images ─────────────────────────────────────────
43 this.imageBuilder, // ImageBuilder?
44 this.onImageTap, // void Function(String url)?
45
46 // ── Lists ──────────────────────────────────────────
47 this.orderedListBuilder, // OrderedListBuilder?
48 this.unOrderedListBuilder, // UnOrderedListBuilder?
49
50 // ── Tables ─────────────────────────────────────────
51 this.tableBuilder, // TableBuilder?
52
53 // ── Headings ───────────────────────────────────────
54 this.headingBuilder, // HeadingBuilder?
55
56 // ── Block quotes ───────────────────────────────────
57 this.blockQuoteBuilder, // BlockQuoteBuilder?
58
59 // ── Checkboxes / radio ─────────────────────────────
60 this.checkboxBuilder, // CheckboxBuilder?
61 this.radioOptionBuilder, // RadioOptionBuilder?
62 this.onCheckboxChanged, // void Function(bool value)?
63
64 // ── Horizontal rules ───────────────────────────────
65 this.hrBuilder, // HrBuilder?
66
67 // ── Source tags (citations) ────────────────────────
68 this.inlineSourceTagBuilder, // InlineSourceTagBuilder?
69 ('Use inlineSourceTagBuilder. Will be removed in 2.0.0.')
70 this.sourceTagBuilder, // SourceTagBuilder?
71 this.onSourceTagTap, // void Function(String content)?
72
73 // ── Copy ───────────────────────────────────────────
74 this.onCodeCopy, // void Function(String code)?
75
76 // ── Custom components ──────────────────────────────
77 this.blockComponents, // List<MarkdownBlockComponent>?
78 this.inlinePatterns, // List<InlinePattern>? — @mention, #channel, :emoji:
79 this.inlineDirectives, // List<InlineDirective>? — opaque delimited regions
80 ('Use blockComponents. Will be removed in 2.0.0.')
81 this.components,
82 ('Use inlinePatterns or inlineDirectives. Will be removed in 2.0.0.')
83 this.inlineComponents,
84
85 // ── Streaming ──────────────────────────────────────
86 this.animation = GptMarkdownAnimation.none,
87 this.blockAnimation = GptMarkdownBlockAnimation.none,
88 this.isStreaming = true,
89 this.charactersPerSecond = 300,
90 this.revealFadeSeconds = 0.25,
91 this.blockAnimationDuration = const Duration(milliseconds: 200),
92 this.blockAnimationCurve = Curves.easeOut,
93
94 ('Remove this argument; plusparse is the default.')
95 this.incremental = true,
96})All parameters show reference
Open a category only when you need to look up a specific option.
Text
| Parameter | Type | Req. | Description |
|---|---|---|---|
| data | String | ✅ | The Markdown string to render. Positional. |
| style | TextStyle? | Base text style applied to all text. | |
| textDirection | TextDirection | LTR (default) or RTL for Arabic, Hebrew, etc. | |
| textAlign | TextAlign? | Text alignment within the widget. | |
| textScaler | TextScaler? | Scales text size; also propagated to inline widgets via MediaQuery. | |
| maxLines | int? | Limit rendered lines. null = unlimited. | |
| overflow | TextOverflow? | Overflow behaviour when maxLines is set. |
Appearance
| Parameter | Type | Req. | Description |
|---|---|---|---|
| styleSheet | GptMarkdownStyleSheet? | 12 per-component style objects. Widget values win over theme values per field. | |
| inlineCodeStyle | InlineCodeStyle? | Inline code style for this widget only. Unset fields derive from ColorScheme. |
Links
| Parameter | Type | Req. | Description |
|---|---|---|---|
| followLinkColor | bool | If true, links inherit the base text colour instead of linkColor. | |
| onLinkTap | void Function(String url, String title)? | Callback when a Markdown link is tapped. title is the label text. | |
| inlineLinkBuilder | InlineLinkBuilder? | Build a link span from LinkBuildDetails. Prefer details.defaultSpan() to preserve wrapping, selection, and tap handling. | |
| linkBuilder ⚠️ | LinkBuilder? (deprecated) | Deprecated widget builder. Use inlineLinkBuilder; WidgetSpan output cannot wrap and is skipped by selection. |
Autolinks
| Parameter | Type | Req. | Description |
|---|---|---|---|
| autolink | bool | Bare URLs, www. hosts, emails and <…> autolinks become links. Default true. | |
| autolinkSchemes | Set<String> | Extra URI schemes linked bare (http/https/mailto/xmpp always included). |
LaTeX
| Parameter | Type | Req. | Description |
|---|---|---|---|
| useDollarSignsForLatex | bool | Enable $…$ and $$…$$ syntax in addition to \(…\) and \[…\]. | |
| latexWorkaround | String Function(String)? | Transform LaTeX strings before rendering (normalise AI output quirks). | |
| latexBuilder | LatexBuilder? | Replace the default LaTeX renderer. inline is true for \(…\). |
Code
| Parameter | Type | Req. | Description |
|---|---|---|---|
| codeBuilder | CodeBlockBuilder? | Replace the fenced code block renderer. closed is false while still streaming. | |
| inlineCodeBuilder | InlineCodeBuilder? | Replace inline `code` span. Return CodeTextSpan to retain the painted chip, baseline alignment, selection, and wrapping; another TextSpan drops the chip. | |
| highlightBuilder ⚠️ | HighlightBuilder? (deprecated) | Deprecated. Returns Widget, causing baseline/selection/iOS issues. Use inlineCodeStyle or inlineCodeBuilder. | |
| onCodeCopy | void Function(String code)? | Called with the code string after the copy button is used. |
Images
| Parameter | Type | Req. | Description |
|---|---|---|---|
| imageBuilder | ImageBuilder? | Replace the image renderer. width/height come from alt text parsed as WxH. | |
| onImageTap | void Function(String url)? | Called with the image URL when an image is tapped. |
Lists
| Parameter | Type | Req. | Description |
|---|---|---|---|
| orderedListBuilder | OrderedListBuilder? | Replace the ordered list item renderer. no is the number string, e.g. '1'. | |
| unOrderedListBuilder | UnOrderedListBuilder? | Replace the unordered list item renderer. |
Tables
| Parameter | Type | Req. | Description |
|---|---|---|---|
| tableBuilder | TableBuilder? | Replace the table renderer. Receives List<CustomTableRow>, the resolved TextStyle and GptMarkdownConfig. |
Headings
| Parameter | Type | Req. | Description |
|---|---|---|---|
| headingBuilder | HeadingBuilder? | Replace the whole heading widget. level is 1–6. Owns the h1 divider rule. |
Block quotes
| Parameter | Type | Req. | Description |
|---|---|---|---|
| blockQuoteBuilder | BlockQuoteBuilder? | Replace the whole blockquote. content is already-rendered; style is resolved BlockQuoteStyle. |
Checkboxes
| Parameter | Type | Req. | Description |
|---|---|---|---|
| checkboxBuilder | CheckboxBuilder? | Replace the task-list checkbox row. Wire taps through onCheckboxChanged. | |
| radioOptionBuilder | RadioOptionBuilder? | Replace the radio option row. | |
| onCheckboxChanged | void Function(bool)? | Called on checkbox tap. Only fires when CheckboxStyle(interactive: true). |
Horizontal rules
| Parameter | Type | Req. | Description |
|---|---|---|---|
| hrBuilder | HrBuilder? | Replace the horizontal rule. style is the resolved HrStyle. |
Citations
| Parameter | Type | Req. | Description |
|---|---|---|---|
| inlineSourceTagBuilder | InlineSourceTagBuilder? | Build a [1] citation span from SourceTagBuildDetails. Use details.defaultSpan() or details.asWidgetSpan(). | |
| sourceTagBuilder ⚠️ | SourceTagBuilder? (deprecated) | Deprecated widget builder. Use inlineSourceTagBuilder. | |
| onSourceTagTap | void Function(String)? | Called with the tag content when a citation chip is tapped. |
Custom
| Parameter | Type | Req. | Description |
|---|---|---|---|
| blockComponents | List<MarkdownBlockComponent>? | Register pure syntax plus a builder for custom blocks without selecting the legacy parser. | |
| inlinePatterns | List<InlinePattern>? | @mention, #channel, :emoji: patterns. Matched ahead of built-ins. Default scope excludes link labels. | |
| inlineDirectives | List<InlineDirective>? | Protect delimited, non-Markdown payloads from the parser. |
Deprecated parser
| Parameter | Type | Req. | Description |
|---|---|---|---|
| components ⚠️ | List<MarkdownComponent>? (deprecated) | Use blockComponents. Passing this argument, even empty, selects the legacy regex parser. | |
| inlineComponents ⚠️ | List<MarkdownComponent>? (deprecated) | Use inlinePatterns or inlineDirectives. Passing it selects the legacy regex parser. | |
| incremental ⚠️ | bool (deprecated) | Delete this argument. plusparse is the default; false selects the legacy parser. |
Streaming
| Parameter | Type | Req. | Description |
|---|---|---|---|
| animation | GptMarkdownAnimation | Character reveal: none, typewriter, fade, blurIn, or wave. | |
| blockAnimation | GptMarkdownBlockAnimation | Independent block entrance: none, fadeIn, growIn, slideUp, or scaleIn. | |
| isStreaming | bool | Whether more text may still arrive. Flip to false when the stream ends. | |
| charactersPerSecond | double | Baseline reveal speed. The reveal auto-accelerates when behind the incoming text. | |
| revealFadeSeconds | double | Time for a newly revealed character to settle. Default 0.25; no visual effect on typewriter. | |
| blockAnimationDuration | Duration | Block entrance duration. Default 200 ms. | |
| blockAnimationCurve | Curve | Block entrance curve. Default Curves.easeOut. |
Lower-level rendering APIs show
Most apps should use GptMarkdown and its builders. Integrations that already own parsed content can call PlusparseRenderer.renderDocument(context, document, config). Use PlusparseRenderer.render(context, source, config) when the renderer should parse the source first.
autolinkSpans(context, text, config) exposes the character scanner used for bare URLs, www. hosts, email addresses, angle autolinks, and schemes supplied through autolinkSchemes. It returns inline spans for a host-owned text pipeline.
When rendering a custom-block AST directly, pass the same block registry to parsing and matching blockComponents to the render configuration.
Builder & callback signatures show reference
Builder arguments depend on the component. Builders that accept a style receive the resolved style; other builders receive component data such as code, dimensions, or the streaming closed flag.inlineCodeBuilder returns an InlineSpan. Return a CodeTextSpan to preserve the package's painted chip, baseline alignment, selection, and wrapping; a different TextSpan deliberately drops the chip.
typedefs.dart
1// ── Builders ─────────────────────────────────────────────────────────────────
2
3typedef HeadingBuilder =
4 Widget Function(BuildContext context, int level, Widget content, HeadingStyle style);
5
6typedef BlockQuoteBuilder =
7 Widget Function(BuildContext context, Widget content, BlockQuoteStyle style);
8
9typedef CheckboxBuilder =
10 Widget Function(BuildContext context, bool checked, Widget content, CheckboxStyle style);
11
12typedef RadioOptionBuilder =
13 Widget Function(BuildContext context, bool selected, Widget content, CheckboxStyle style);
14
15typedef HrBuilder = Widget Function(BuildContext context, HrStyle style);
16
17typedef CodeBlockBuilder =
18 Widget Function(BuildContext context, String name, String code, bool closed);
19
20typedef TableBuilder =
21 Widget Function(BuildContext context, List<CustomTableRow> tableRows,
22 TextStyle textStyle, GptMarkdownConfig config);
23
24typedef ImageBuilder =
25 Widget Function(BuildContext context, String imageUrl, double? width, double? height);
26
27typedef LatexBuilder =
28 Widget Function(BuildContext context, String tex, TextStyle textStyle, bool inline);
29
30typedef InlineLinkBuilder =
31 InlineSpan Function(LinkBuildDetails details);
32
33// Returns InlineSpan. Return CodeTextSpan to keep the package's painted,
34// baseline-aligned, selectable, wrappable chip; another TextSpan drops the chip.
35typedef InlineCodeBuilder =
36 InlineSpan Function(BuildContext context, String code, TextStyle style,
37 InlineCodeStyle codeStyle);
38
39typedef InlineSourceTagBuilder =
40 InlineSpan Function(SourceTagBuildDetails details);
41
42typedef OrderedListBuilder =
43 Widget Function(BuildContext context, String no, Widget child, GptMarkdownConfig config);
44
45typedef UnOrderedListBuilder =
46 Widget Function(BuildContext context, Widget child, GptMarkdownConfig config);
47
48// ── Deprecated ───────────────────────────────────────────────────────────────
49
50// highlightBuilder: returns Widget (wrapped in WidgetSpan — cannot wrap across
51// lines, skipped by selection, invisible on iOS inside a link label).
52// Deprecated in v1.2.0. Will be removed in 2.0.0.
53// Prefer inlineCodeStyle for restyling, or inlineCodeBuilder for a custom span.
54('Use inlineCodeBuilder. Will be removed in 2.0.0.')
55typedef HighlightBuilder =
56 Widget Function(BuildContext context, String text, TextStyle style);Migrating from highlightBuilder show migration
Deprecated — scheduled for removal in 2.0.0
highlightBuilder returned a Widget wrapped in a WidgetSpan at a hardcoded PlaceholderAlignment.middle. That placement sat off the baseline, could not wrap across lines, was skipped by text selection, and did not paint on iOS inside a link label. Most callers only needed restyling and no longer need a builder at all.
migration.dart
1// Before (highlightBuilder — deprecated)
2GptMarkdown(
3 text,
4 highlightBuilder: (context, code, style) => MyChip(code, style),
5)
6
7// After — restyle only, no builder needed
8GptMarkdown(
9 text,
10 inlineCodeStyle: const InlineCodeStyle(fontFamily: 'GeistMono'),
11)
12
13// After — custom span (stays on baseline, wraps, stays selectable)
14GptMarkdown(
15 text,
16 inlineCodeBuilder: (context, code, style, codeStyle) => CodeTextSpan(
17 text: code,
18 style: style,
19 codeStyle: codeStyle.copyWith(
20 backgroundColor: code.startsWith('TODO') ? Colors.amber : null,
21 ),
22 ),
23)
24
25// After — widget genuinely required
26GptMarkdown(
27 text,
28 inlineCodeBuilder: (context, code, style, codeStyle) =>
29 baselineWidgetSpan(MyChip(code: code, style: style)),
30)Builder & callback matrix show reference
Use this as a lookup table when you know which component you want to replace.
| Component | Style class | Builder param | Callback param |
|---|---|---|---|
| Heading | HeadingStyle | headingBuilder | — |
| Block quote | BlockQuoteStyle | blockQuoteBuilder | — |
| Horizontal rule | HrStyle | hrBuilder | — |
| Checkbox / task list | CheckboxStyle | checkboxBuilder | onCheckboxChanged |
| Radio option | CheckboxStyle | radioOptionBuilder | onCheckboxChanged |
| Fenced code block | CodeBlockStyle | codeBuilder | onCodeCopy |
| Inline code | InlineCodeStyle | inlineCodeBuilder | — |
| Table | TableStyle | tableBuilder | — |
| Image | ImageStyle | imageBuilder | onImageTap |
| Link | LinkStyle | inlineLinkBuilder | onLinkTap |
| Ordered list item | ListStyle | orderedListBuilder | — |
| Unordered list item | ListStyle | unOrderedListBuilder | — |
| LaTeX (block & inline) | LatexStyle | latexBuilder | — |
| Citation chip [1] | SourceTagStyle | inlineSourceTagBuilder | onSourceTagTap |
Common mistakes show tips
Changing a builder at runtime does nothing
GptMarkdownConfig.isSame cannot compare closures — a consumer that writes builders inline creates a new one every build, so span regeneration would happen on every frame. Builder changes therefore require a key change or a remount. Style objects compare by value and update live. Pattern and component lists use element identity: rebuilding the list is fine when it contains the same instances, but replace an element instance when its matching behavior changes.
A raw WidgetSpan scales twice
A paragraph lays inline children out in scaled space and multiplies their reported size back. A child that also scales its own text is counted twice — up to 39× excess at a 2× system font setting. Use baselineWidgetSpan, or wrap the child in MediaQuery.withNoTextScaling. InlinePattern does this for you.