Custom Components

For syntax the package does not know about — callout boxes, mention chips, custom citation styles.

Reach for this last

For @mention-style tokens use InlinePattern — no subclassing, and it handles nesting rules correctly by default. For appearance use a style object. A custom component is for genuinely new syntax.

blockComponents

Block components

Parse custom blocks with syntax + a builder

inlinePatterns

Inline patterns

Match @mention, #channel, and :emoji: tokens

inlineDirectives

Inline directives

Protect delimited payloads from Markdown parsing

Keep the modern pipeline

In 1.3, built-in syntax stays registered automatically. Use blockComponents for new block syntax and inlinePatterns or inlineDirectives for inline extensions. Passing the deprecated components or inlineComponents lists opts into the legacy parser and can silently disable caching and lazy rendering.

two_lists.dart

// Do not pass the deprecated legacy lists in 1.3.
// Even an empty components list selects the legacy regex parser.
GptMarkdown(
  text,
  blockComponents: [
    MarkdownBlockComponent(
      syntax: const FencedBlockSyntax(
        type: 'callout',
        opening: ':::callout',
      ),
      builder: (context, node, config) => CalloutBox(body: node.body),
    ),
  ],
  inlinePatterns: [mentionPattern],
)

// Built-ins stay registered automatically. Use inlineDirectives when
// the parser must not inspect a delimited payload.

InlinePattern — simple pattern

The recommended API for app-specific inline tokens in v1.3.0. Patterns are matched ahead of built-in components. No subclassing required.

inline_pattern.dart

import 'package:flutter/gestures.dart';
import 'package:flutter/material.dart';
import 'package:gpt_markdown/gpt_markdown.dart';

// inlinePatterns — the recommended API for @mention / #channel / :emoji:
// No subclassing. Matched AHEAD of built-in components.

GptMarkdown(
  text,
  inlinePatterns: [
    InlinePattern(
      // Anchor with lookarounds, not ^ — patterns match the whole document.
      pattern: RegExp(r'(?<![w-])GH-(d+)'),
      builder: (context, match, style) => TextSpan(
        text: match.group(0),
        style: style.copyWith(
          color: Theme.of(context).colorScheme.primary,
          fontWeight: FontWeight.w600,
        ),
        recognizer: TapGestureRecognizer()
          ..onTap = () => openIssue(match.group(1)!),
      ),
      // TextSpan is safe inside link labels — opt back in:
      scopes: MarkdownComponent.allScopes,
    ),
  ],
)

Advanced component authoring show advanced options

InlinePattern.prefixed — @mention & #channel

The InlinePattern.prefixed factory handles boundary rules automatically: @user in an email address is not claimed, and #frag in a URL fragment is not claimed. Longer names win over shorter ones (longest-first matching).

inline_pattern_prefixed.dart

// InlinePattern.prefixed — helper for @name and #channel.
// Handles boundary rules so @user in user@example.com is not claimed,
// and #frag in https://x.com/#frag is not claimed.

GptMarkdown(
  text,
  inlinePatterns: [
    InlinePattern.prefixed(
      prefix: '#',
      // Longer names win — #design-review is not shadowed by #design.
      knownNames: channelNames,   // ['general', 'design-review', …]
      builder: (context, match, style) => WidgetSpan(
        alignment: PlaceholderAlignment.baseline,
        baseline: TextBaseline.alphabetic,
        child: ChannelChip(name: match.group(0)!.substring(1)),
      ),
      // Default scope already excludes link labels (WidgetSpan safety).
      // scopes: MarkdownComponent.allScopesExceptLinkLabel,
    ),
    InlinePattern.prefixed(
      prefix: '@',
      knownNames: memberNames,
      builder: (context, match, style) => TextSpan(
        text: match.group(0),
        style: style.copyWith(color: Colors.indigo),
        recognizer: TapGestureRecognizer()
          ..onTap = () => openProfile(match.group(0)!.substring(1)),
      ),
      // Returns TextSpan — safe to include link labels:
      scopes: MarkdownComponent.allScopes,
    ),
  ],
)

// Leave genericTokenPattern null to match ONLY known names.
// A generic fallback chips #2959 when the author meant issue 2959 — a real
// production bug. Only supply one when you genuinely want every #token.

InlinePattern.delimited — :emoji: & ::spoiler::

The InlinePattern.delimited factory handles tokens with a closing delimiter, which prefixed cannot express. knownNames and genericTokenPattern behave exactly as they do on prefixed: known names match exactly, longest first, and leaving the generic pattern null matches only those names.

inline_pattern_delimited.dart

// InlinePattern.delimited — for tokens with a CLOSING delimiter.
// prefixed cannot express :tada: — it would match :tada and leave a
// stray colon behind. The token name is the named group 'name' (and group 1).

const emoji = {'tada': '🎉', 'rocket': '🚀', 'fire': '🔥'};

GptMarkdown(
  text,
  inlinePatterns: [
    InlinePattern.delimited(
      open: ':',              // close defaults to open
      knownNames: emoji.keys,
      builder: (context, match, style) {
        final name = match.namedGroup('name');
        final glyph = name == null ? null : emoji[name];
        // Unknown name → return the raw match, never an empty span.
        return TextSpan(text: glyph ?? match.group(0), style: style);
      },
    ),
    // Asymmetric, multi-character delimiters work too:
    InlinePattern.delimited(
      open: '{{',
      close: '}}',
      knownNames: templateNames,
      builder: buildTemplateSpan,
    ),
  ],
)

// Boundaries are handled: 10:30:45 and http://host:8080/x are not claimed,
// :tada:xyz does not match, but adjacent :fire::fire: matches twice.

Static helpers — buildPrefixedPattern & buildDelimitedPattern

When a factory is not flexible enough — you need custom scopes reasoning, or the regex inside your own MarkdownComponent subclass — InlinePattern.buildPrefixedPattern and InlinePattern.buildDelimitedPattern return the exact regexes the factories use, so the boundary rules stay correct without re-deriving them.

pattern_helpers.dart

// The regexes behind both factories are exposed as static helpers, for
// building your own InlinePattern or MarkdownComponent while keeping the
// fiddly boundary rules, longest-name-first matching, and case-insensitivity.

// 1. buildPrefixedPattern — same rules as prefixed, your own pattern object.
//    Here: a TextSpan-only mention opted into EVERY scope, link labels included.
InlinePattern(
  pattern: InlinePattern.buildPrefixedPattern(
    prefix: '@',
    knownNames: userDirectory.handles,
    // genericTokenPattern: r'[A-Za-z0-9_]+', // optional fallback
  ),
  builder: (context, match, style) => TextSpan(
    text: match.group(0),
    style: style.copyWith(color: Colors.indigo, fontWeight: FontWeight.w600),
    recognizer: TapGestureRecognizer()
      ..onTap = () => openProfile(match.group(0)!.substring(1)),
  ),
  scopes: MarkdownComponent.allScopes, // safe: builder returns a TextSpan
)

// 2. buildDelimitedPattern — the delimited regex inside a custom component.
//    Discord-style ||spoiler||, hidden text available as named group 'name'.
class SpoilerMd extends InlineMd {
  @override
  RegExp get exp => InlinePattern.buildDelimitedPattern(
        open: '||',
        genericTokenPattern: r'[^|\n]+', // tight, non-capturing
      );

  @override
  Set<MarkdownScope> get scopes => MarkdownComponent.allScopesExceptLinkLabel;

  @override
  InlineSpan span(BuildContext context, String text, GptMarkdownConfig config) {
    final hidden = exp.firstMatch(text)?.namedGroup('name') ?? text;
    return WidgetSpan(
      alignment: PlaceholderAlignment.baseline,
      baseline: TextBaseline.alphabetic,
      child: SpoilerChip(text: hidden, style: config.style),
    );
  }
}

// Register the component — keep the built-ins:
GptMarkdown(
  text,
  inlineComponents: [SpoilerMd(), ...MarkdownComponent.inlineComponents],
)

// Write genericTokenPattern as tightly as the syntax allows and use
// non-capturing groups — a loose .+ runs past the closing delimiter and
// swallows the rest of the line.

// Empty inputs return a regex that can never match, and the renderer skips
// the pattern entirely — server-loaded lists need no guard at the call site:
InlinePattern.buildPrefixedPattern(
  prefix: '#',
  knownNames: channelsFromServer, // may be empty
)

Legacy inline component reference

Existing InlineMd subclasses still compile until 2.0. Prefer InlinePattern for text matched in the document, or InlineDirective for opaque delimited payloads. Keeping the old subclass means keeping the legacy registration path.

shout_md.dart

import 'package:flutter/material.dart';
import 'package:gpt_markdown/gpt_markdown.dart';

// Renders !!SHOUT!! in uppercase bold.
class ShoutMd extends InlineMd {
  @override
  RegExp get exp => RegExp(r'!![A-Za-z]+!!');

  // allScopesExceptLinkLabel prevents a WidgetSpan from nesting inside
  // the link's own WidgetSpan — which does not paint on iOS.
  @override
  Set<MarkdownScope> get scopes => MarkdownComponent.allScopesExceptLinkLabel;

  @override
  InlineSpan span(BuildContext context, String text, GptMarkdownConfig config) {
    // text is the whole matched string; re-run the regex for groups.
    return TextSpan(
      text: text.replaceAll('!!', '').toUpperCase(),
      style: config.style?.copyWith(fontWeight: FontWeight.bold),
    );
  }
}

// Register — keep built-in inline syntax:
GptMarkdown(
  'This is !!important!! text.',
  inlineComponents: [ShoutMd(), ...MarkdownComponent.inlineComponents],
)

Legacy block component reference

Existing BlockMd subclasses still work until 2.0, but they select the legacy regex parser. Use MarkdownBlockComponent with a pure MarkdownBlockSyntax instead; the modern version can be cached and rendered lazily by SliverGptMarkdown.

callout_md.dart

import 'package:flutter/material.dart';
import 'package:gpt_markdown/gpt_markdown.dart';

// Renders :::warning\n…\n::: as a styled callout box.
class CalloutMd extends BlockMd {
  @override
  String get expString => r':::(w+)
([sS]*?)
:::';

  @override
  Widget build(BuildContext context, String text, GptMarkdownConfig config) {
    final match = exp.firstMatch(text);
    final kind = match?.group(1) ?? 'note';
    final body = match?.group(2) ?? '';

    return Container(
      padding: const EdgeInsets.all(12),
      decoration: BoxDecoration(
        color: Theme.of(context).colorScheme.surfaceContainerHighest,
        borderRadius: BorderRadius.circular(8),
      ),
      child: Row(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Icon(kind == 'warning' ? Icons.warning : Icons.info),
          const SizedBox(width: 8),
          // Recurse — render body as Markdown too.
          Flexible(child: GptMarkdown(body, style: config.style)),
        ],
      ),
    );
  }
}

// Register — keep built-in block syntax:
GptMarkdown(
  text,
  components: [CalloutMd(), ...MarkdownComponent.globalComponents],
)

MarkdownScope safety

A component declares which nesting contexts it renders in. Without this, a WidgetSpan inside a link label produces a nested placeholder that does not paint on iOS — invisible text, no error, nothing in the logs.

markdown_scope.dart

// MarkdownScope — where a component is allowed to render.
//
// enum MarkdownScope { content, linkLabel, tableCell, heading }
//
// allScopes                — every context (default for all components)
// allScopesExceptLinkLabel — everything except inside [label](url)
//
// A WidgetSpan nested inside a link's WidgetSpan does not paint on iOS.
// Declare allScopesExceptLinkLabel on any component that returns a WidgetSpan.

class MyChipMd extends InlineMd {
  @override
  Set<MarkdownScope> get scopes => MarkdownComponent.allScopesExceptLinkLabel;

  @override
  RegExp get exp => RegExp(r'#[A-Za-z0-9_-]+');

  @override
  InlineSpan span(BuildContext context, String text, GptMarkdownConfig config) {
    return WidgetSpan(
      child: MediaQuery.withNoTextScaling(child: MyChip(text)),
    );
  }
}

// Alternatively, restrict to prose only:
// scopes: const {MarkdownScope.content}

MarkdownScope values

Scope	Where
content	Ordinary document and inline text. The default.
linkLabel	Inside the label half of [label](url).
tableCell	Inside a table cell.
heading	Inside a # heading.

MarkdownComponent.allScopes — all four. MarkdownComponent.allScopesExceptLinkLabel — content, tableCell, heading. InlinePattern defaults to allScopesExceptLinkLabel.

Source tags / citations

The package has first-class support for AI citation chips ([1], [2], …) common in RAG answers. Use inlineSourceTagBuilder to replace the chip span, or just onSourceTagTap to handle taps without replacing it. Style the default chip with styleSheet: GptMarkdownStyleSheet(sourceTag: SourceTagStyle(…)).

source_tags.dart

// Built-in support for AI citation chips: [1], [2], …
// sourceTagBuilder receives the content between the brackets.

GptMarkdown(
  content,
  sourceTagBuilder: (context, content, textStyle) {
    return GestureDetector(
      onTap: () => openSource(content),
      child: Container(
        margin: const EdgeInsets.only(left: 2),
        padding: const EdgeInsets.symmetric(horizontal: 5, vertical: 1),
        decoration: BoxDecoration(
          color: Theme.of(context).colorScheme.primaryContainer,
          borderRadius: BorderRadius.circular(4),
        ),
        child: Text(
          content,
          style: textStyle.copyWith(fontSize: 11),
        ),
      ),
    );
  },
  // Or use the callback without replacing the widget:
  onSourceTagTap: (content) => showSource(content),
)

TextSpan vs WidgetSpan

Prefer a TextSpan wherever the design allows. A WidgetSpan introduces layout constraints that affect selection, line-wrapping, and iOS rendering.

span_guidance.dart

// TextSpan — prefer this when possible.
//   ✅ Stays selectable
//   ✅ Wraps across lines
//   ✅ Sits on text baseline
//   ✅ Safe inside link labels ([label](url))

builder: (context, match, style) => TextSpan(
  text: match.group(0),
  style: style.copyWith(color: Colors.indigo),
),

// WidgetSpan — only when a real widget is needed (icon, rounded chip, image).
//   ⚠️ Cannot wrap across lines
//   ⚠️ Excluded from text selection
//   ⚠️ MUST be excluded from link labels (allScopesExceptLinkLabel) or
//      it renders as nothing on iOS — no error, no warning.
//   ⚠️ MUST suppress text scaling or it reserves far more space than needed.

// Wrong at raised text scales:
return WidgetSpan(child: MyChip());

// Right — scale compensation + baseline alignment:
return baselineWidgetSpan(MyChip());
// or:
return WidgetSpan(child: MediaQuery.withNoTextScaling(child: MyChip()));

// InlinePattern and InlinePatternMd do scale compensation automatically.

Ordering & matching caveats

ordering.dart

// List order controls two things:
//   1. Which alternative the combined regex matches (first match wins).
//   2. Which handler claims that match.
// Earlier items win both — prepend to override a built-in.

// Cache the component instances. The config compares list entries by identity:
// a fresh list with the same instances is fine, but a new component instance
// tells the renderer to regenerate its spans.
late final _inline = [ShoutMd(), ...MarkdownComponent.inlineComponents];

GptMarkdown(text, inlineComponents: _inline)

// On failure, return the source text — never an empty span:
// Wrong:  if (match == null) return const TextSpan();
// Right:  if (match == null) return TextSpan(text: text, style: config.style);

// Case sensitivity is contagious: one caseSensitive: false component makes
// the entire combined regex case-insensitive.

Patterns with a top-level | need grouping

The combined regex anchors each component as ^(?:pattern)$. Without the non-capturing group, a top-level | in a component pattern would have ^ bind to the first alternative and $ to the last — claiming matches the component does not actually cover. The package wraps your pattern in (?:…) so this is handled, but verify your component's own alternation behaves as expected.

Case sensitivity is contagious

The combined regex carries one set of flags. One component with caseSensitive: false makes the whole alternation case-insensitive — required for that component to match, but it affects the others too.

Test a custom component, including a link label

Markdown output is a span tree, so assert on the rendered RichText content. Also include a fixture inside a link label: that is where an unsafe WidgetSpan silently fails on iOS. With MarkdownComponent.allScopesExceptLinkLabel, [!!loud!!](https://x.com) must remain literal inside the label rather than becoming a nested chip.

custom_component_test.dart

testWidgets('renders in caps', (tester) async {
  await tester.pumpWidget(
    MaterialApp(
      home: Scaffold(
        body: GptMarkdown(
          'a !!loud!! word',
          inlinePatterns: [shoutPattern],
        ),
      ),
    ),
  );
  await tester.pumpAndSettle();

  final buffer = StringBuffer();
  for (final richText in tester.widgetList<RichText>(
    find.byWidgetPredicate((widget) => widget is RichText),
  )) {
    buffer.write(richText.text.toPlainText(includePlaceholders: false));
  }
  expect(buffer.toString(), contains('LOUD'));

  // Also test '[!!loud!!](https://x.com)': with
  // allScopesExceptLinkLabel it stays literal rather than becoming a nested chip.
})

← API Reference