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.

components

Block components

Match multi-line patterns; return a Widget

inlineComponents

Inline components

Match within a line; return an InlineSpan

inlinePatterns

InlinePattern (v1.2.0)

@mention, #channel, :emoji: — no subclassing

Do not wipe the built-ins

Passing a list to components or inlineComponents replaces the defaults entirely. Always append the package defaults to keep bold, links, code, and all other built-in syntax working.

two_lists.dart

// components    → block pass: headings, lists, tables, fences, …
// inlineComponents → inline pass: bold, links, code, images, …

GptMarkdown(
  text,
  components: [...],
  inlineComponents: [...],
)

// WARNING: passing a list REPLACES the defaults — bold, links, and code
// stop working unless you keep the built-ins.

// Wrong — loses all built-in inline syntax:
inlineComponents: [MyComponent()],

// Right — prepend your component, keep built-ins:
inlineComponents: [MyComponent(), ...MarkdownComponent.inlineComponents],

// Block list equivalent:
components: [MyBlockComponent(), ...MarkdownComponent.globalComponents],

InlinePattern — simple pattern

The recommended API for app-specific inline tokens in v1.2.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
)

Inline component (subclass)

Extend InlineMd when you need more control than InlinePattern provides. The span method returns an InlineSpan.

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],
)

Block component (subclass)

Extend BlockMd, override expString, and return a Widget from build. BlockMd.exp is built automatically from expString.

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 sourceTagBuilder to replace the chip widget, 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',
          inlineComponents: [ShoutMd(), ...MarkdownComponent.inlineComponents],
        ),
      ),
    ),
  );
  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