Basic Usage

Everything from install to a production-ready render, with GptMarkdown v1.2.1.

Install

pubspec.yaml

# pubspec.yaml
dependencies:
  gpt_markdown: ^1.2.1

import

import 'package:gpt_markdown/gpt_markdown.dart';

One import brings in the widget, every style class, all builder typedefs, and GptMarkdownConfig.

Minimal render

One positional argument — the markdown string. Everything else is optional.

main.dart

// Minimum: one positional argument — the markdown string.
GptMarkdown('# Hello\n\nSome **bold** text and `inline code`.')

What it supports

Feature	Syntax or behavior
Headings	# through ######
Emphasis	bold, italic, ~~strike~~, <u>underline</u>
Code	`inline` and fenced code blocks
Lists	Bulleted, ordered, nested, task lists, and radio options
Tables	GFM-style tables, including :---: alignment
Blocks	Quotes, rules, images, links, citations, and bare autolinks
Math	\( inline \) and \[ block \]; dollar signs are opt-in

The package has no platform-specific plugins and is suitable for Flutter Web, including WebAssembly-targeted builds. Your app's other dependencies must still support the WebAssembly target.

Scrollable replies

Important: GptMarkdown sizes itself to its content. Put it inside something scrollable for anything longer than a sentence — otherwise a long reply overflows the screen.

reply_view.dart

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

/// GptMarkdown sizes itself to its content and does not scroll.
/// Wrap it whenever the reply may exceed the screen height.
class ReplyView extends StatelessWidget {
  final String reply;
  const ReplyView({super.key, required this.reply});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Reply')),
      body: SingleChildScrollView(
        padding: const EdgeInsets.all(16),
        child: GptMarkdown(reply),
      ),
    );
  }
}

In a chat list where the ListView already scrolls:

chat_list.dart

// One GptMarkdown per bubble — no scroll wrapper needed
// because the ListView itself scrolls.
ListView.builder(
  itemCount: messages.length,
  itemBuilder: (context, i) => Padding(
    padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
    child: GptMarkdown(messages[i].text),
  ),
)

Text selection

Wrap in SelectionArea the same way you would any Flutter text. Inline code stays on the text baseline and is selectable. Copying across a list or table currently yields cells run together with no separators — prose, headings, links, and inline code copy correctly.

selectable.dart

// Wrap in SelectionArea to make all text inside selectable.
SelectionArea(
  child: SingleChildScrollView(
    padding: const EdgeInsets.all(16),
    child: GptMarkdown(reply),
  ),
)

Handling link taps

Links render as tappable but do nothing on their own — opening a URL is your decision. LLM output can contain any URL, so validate before launching.

link_tap.dart

// Links do nothing unless you handle them.
// The package does not depend on a URL launcher — that choice is yours.
GptMarkdown(
  reply,
  onLinkTap: (url, title) {
    final uri = Uri.tryParse(url);
    if (uri == null) return;
    if (uri.scheme != 'https' && uri.scheme != 'mailto') return;
    launchUrl(uri);
  },
)

Image, code, citation, and checkbox callbacks

The remaining interactions are opt-in too. Markdown checkboxes are read-only by default; when enablingCheckboxStyle(interactive: true), persist a rewritten source string or the visible state will revert during the next rebuild.

interactions.dart

GptMarkdown(
  reply,
  onImageTap: (url) => openLightbox(url),
  onCodeCopy: (code) => analytics.log('code_copied'),
  onSourceTagTap: (content) => showSource(content),
  // Requires CheckboxStyle(interactive: true).
  onCheckboxChanged: (value) => persistCheckbox(value),
)

Right-to-left

Inline widgets — LaTeX, images, links — are placed in the correct visual order in mixed-direction paragraphs, working around flutter#54400 which the framework does not handle on its own.

rtl.dart

GptMarkdown(
  reply,
  textDirection: TextDirection.rtl,
)

Text scaling

Set the base font size once via style. Heading sizes, inline code, and list bullets all derive from it proportionally. Components rendered as inline widgets scale correctly at any system font setting.

text_style.dart

// Base text style — component sizes derive from this.
// Set it once here; do not set sizes in individual style classes.
GptMarkdown(
  reply,
  style: const TextStyle(fontSize: 16, height: 1.6),
)

// Or pull from the theme:
GptMarkdown(
  reply,
  style: Theme.of(context).textTheme.bodyMedium,
)

Streaming AI output

Accumulate tokens in a StringBuffer, pass the string to GptMarkdown, and set isStreaming: true while the stream is open. The settled prefix is cached so cost per token stays flat regardless of reply length. See the Streaming guide for pacing, performance details, and pitfalls.

streaming_reply.dart

// Streaming is data, not a Stream — rebuild with a longer string each token.
class ReplyView extends StatefulWidget {
  const ReplyView({super.key, required this.stream});
  final Stream<String> stream;

  @override
  State<ReplyView> createState() => _ReplyViewState();
}

class _ReplyViewState extends State<ReplyView> {
  final _buffer = StringBuffer();
  bool _generating = true;

  @override
  void initState() {
    super.initState();
    widget.stream.listen(
      (chunk) => setState(() => _buffer.write(chunk)),
      onDone:  () => setState(() => _generating = false),
    );
  }

  @override
  Widget build(BuildContext context) => SingleChildScrollView(
    padding: const EdgeInsets.all(16),
    child: GptMarkdown(
      _buffer.toString(),
      animation: GptMarkdownAnimation.fade,
      isStreaming: _generating,   // flip to false when the stream ends
    ),
  );
}

LaTeX rendering

The package renders LaTeX by default. Use latexBuilder only when your app needs a different math widget or error treatment. See LaTeX Support for delimiters and display-math scroll.

latex.dart

// LaTeX renders with the package default. Use latexBuilder only to replace it.
// flutter_math_fork is the most common choice.
import 'package:flutter_math_fork/flutter_math.dart';

GptMarkdown(
  reply,
  latexBuilder: (context, tex, textStyle, inline) => Math.tex(
    tex,
    textStyle: textStyle,
    onErrorFallback: (err) => Text(tex, style: textStyle),
  ),
)

Custom code block

Use codeBuilder to replace the default code block widget. The closed flag is false while the closing fence has not yet arrived during streaming.

code_block.dart

// Replace the default code block widget with your own.
GptMarkdown(
  reply,
  codeBuilder: (context, name, code, closed) {
    // name   = language identifier ("dart", "python", …) — may be empty
    // code   = raw code string
    // closed = false while the closing fence hasn't arrived yet (streaming)
    return MyCodeBlock(language: name, code: code, isClosed: closed);
  },
)

Custom image renderer

The imageBuilder callback receives the URL plus optional width and height from the alt text (parsed as WxH).

image_builder.dart

GptMarkdown(
  reply,
  imageBuilder: (context, url, width, height) {
    return ClipRRect(
      borderRadius: BorderRadius.circular(8),
      child: Image.network(
        url,
        width: width,
        height: height,
        fit: BoxFit.cover,
      ),
    );
  },
)

Custom link renderer

Use linkBuilder for complete control over how links are drawn. For tap-only needs, prefer the simpler onLinkTap.

link_builder.dart

GptMarkdown(
  reply,
  linkBuilder: (context, text, url, style) {
    return InkWell(
      onTap: () => launchUrlString(url),
      child: Text.rich(TextSpan(children: [text]),
          style: style.copyWith(decoration: TextDecoration.underline)),
    );
  },
)

Common mistakes

Wrapping in Expanded without a scroll view. The widget reports its content height; constraining it with Expanded without a scroll view clips the reply. Always put a SingleChildScrollView between them.

Streaming a long response without the streaming path. The package's measured 7.7 kB / 120-append case is 14.6 ms per token with animation: none versus 11.0 ms with the split/cached fade path, which stays flat as the reply grows. Use the streaming guide for generated replies.

Rebuilding builder closures on every frame. Builders (latexBuilder, codeBuilder, etc.) are not compared when deciding whether to re-render, so a changed closure is silently ignored until the widget remounts. Define them once, outside build, or key the widget if you genuinely need to swap them.

Leaving isStreaming: true after the reply finishes. The ticker keeps running and the tail keeps rebuilding for nothing. Always flip it on onDone — including error paths.