TOML Viewer

Turn a TOML configuration file into a tree your users can actually read.
Expandable, searchable, copyable — and fast enough for files with thousands of keys.

_{Every frame above is rendered by the real widget — see tool/make_gif.sh.}

Contents #

• New here? Start with this
• Why you might want it
• Install
• Your first viewer
• Where the data comes from
• Features
  • Search · Raw source · Expand & collapse · Theming · Styling · Custom rendering · Interaction & clipboard · Errors
• How it works
• Anatomy of a row
• Configuration reference
• Working with the parsed tree
• Public API
• FAQ and troubleshooting
• Upgrading from 1.x
• Requirements
• Contributing

New here? Start with this #

TOML is a plain-text format for configuration files — the settings an app reads when it starts. It's designed to be easy for a person to write, and you'll find it in pubspec-adjacent tooling, Rust's Cargo.toml, Python's pyproject.toml, and countless server configs.

Reading one inside an app is another matter. A settings screen, an admin panel, or a debug tool that dumps raw text makes the user scroll through punctuation hunting for one value.

This package renders that same file as a tree. Sections become branches you open and close, values are colour-coded by type, and there's a search box.

It's one widget. You give it TOML; it gives you the view on the right.

Why you might want it #

Install #

dependencies:
  toml_viewer: ^2.0.0

flutter pub add toml_viewer

Your first viewer (30 seconds) #

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

class ConfigScreen extends StatelessWidget {
  const ConfigScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Configuration')),
      body: const TomlView(
        content: '''
[server]
host = "localhost"
port = 8080

[server.tls]
enabled = true
''',
      ),
    );
  }
}

That's the whole integration. Colours already follow your app's light or dark theme, and rows are already expandable.

Give it a bounded height. TomlView scrolls, so put it in a Scaffold body, an Expanded, or a SizedBox — not directly inside an unbounded Column. To embed it in a scroll view you already have, pass shrinkWrap: true.

Where the data comes from #

Five constructors, one for each place TOML tends to live.

// 1. A string you already have.
TomlView(content: tomlText)

// 2. A Flutter asset declared in pubspec.yaml.
TomlView.asset('assets/config.toml')

// 3. A Map you parsed yourself — or any Map at all, TOML or not.
TomlView.fromMap({'title': 'My App', 'debug': true})

// 4. Anything async: a file, an HTTP response, a database row.
TomlView.loader(() => File('/etc/app/config.toml').readAsString())
TomlView.loader(() async => (await http.get(uri)).body)

// 5. A stream — re-parses and re-renders on every emission.
TomlView.stream(configFileWatcher)

Features #

Search #

TomlView(
  content: toml,
  searchQuery: _searchController.text,
  emptyBuilder: (_) => const Center(child: Text('No matches')),
)

Matching keys and values are highlighted. Every ancestor of a match is kept and force-expanded, so a hit five levels down is reachable without hunting for it. Pass caseSensitiveSearch: true for exact matching.

Wire it to a TextField and rebuild on change — that's all the demo does.

Raw source view #

TomlView(content: toml, mode: TomlViewMode.source)

The original text, with a line-number gutter and every error line tinted. Handy when a user reports "my config isn't working" and you want to show them exactly which line the parser rejected.

TomlSourceView is exported too, if you want it outside a TomlView.

Expand and collapse #

Tap any row with a chevron. For programmatic control, pass a controller:

final controller = TomlExpandController(defaultExpanded: false);

TomlView(content: toml, expandController: controller);

controller.expandAll();
controller.collapseAll();
controller.expandToPath('server.tls');        // opens server, then server.tls
controller.expandToPath('routes[1].method');  // understands array indices

// Persist what the user opened, and put it back next time:
final saved = controller.overrides;
controller.restore(saved);

Theming #

// Follows the ambient Theme's brightness:
TomlView(content: toml)

// Or choose explicitly:
TomlView(content: toml, config: const TomlViewerConfig.dark())

Set it once for a whole subtree with an InheritedWidget:

TomlViewerTheme(
  config: const TomlViewerConfig.dark(
    style: TomlViewerStyle(indentation: 20),
  ),
  child: TomlView(content: toml),
)

A TomlView resolves its config in this order: its own config argument → the nearest TomlViewerTheme → a palette matching the ambient Theme.

Custom colours live in one object:

TomlViewerConfig(
  colors: TomlViewerColors.dark.copyWith(
    value: Colors.amber,
    tableKey: Colors.cyan,
  ),
)

Styling #

TomlView(
  content: toml,
  config: TomlViewerConfig.of(context).copyWith(
    style: const TomlViewerStyle(
      rootKeyStyle: TextStyle(fontSize: 16, fontWeight: FontWeight.bold),
      indentation: 24,
      separator: ' : ',
      collapsedIcon: Icons.add_circle_outline,
      expandedIcon: Icons.remove_circle_outline,
    ),
  ),
)

There's a monospaced preset, and a font stack that actually resolves to a monospaced face on every platform (plain 'monospace' doesn't, on iOS, macOS, or the web):

config.copyWith(style: TomlViewerStyle.monospace)

const TextStyle(
  fontFamily: 'monospace',
  fontFamilyFallback: TomlViewerStyle.monospaceFallback,
)

copyWith only ever sets values — passing null means "leave unchanged". To remove one, use clear:

// Hide the expand icons, and let long values wrap instead of ellipsising:
style.clear(collapsedIcon: true, expandedIcon: true, maxValueLines: true)

Custom rendering #

Three builders, each replacing a different amount. Return null from any of them to fall back to the default.

TomlViewerConfig(
  // Just the value:
  valueBuilder: (context, value, path) =>
      value is bool ? Icon(value ? Icons.check : Icons.close) : null,

  // Just the key:
  keyBuilder: (context, key, path, isRoot) => Text(key.toUpperCase()),

  // The entire row, expand icon and all:
  rowBuilder: (context, key, value, path, isExpanded, onToggle) => null,
)

Interaction and clipboard #

TomlViewerConfig(
  copyMode: TomlCopyMode.pathAndValue, // long-press copies "server.port = 8080"
  onValueTap: (context, key, value, path) => print('$path = $value'),
  onValueCopied: (context, key, copied, path) =>
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Copied $copied')),
      ),
)

TomlCopyMode is value (the default), path, pathAndValue, or none. The tree is also wrapped in a SelectionArea, so ordinary text selection works — turn that off with enableTextSelection: false.

Error handling #

A broken TOML file doesn't produce an empty screen. The parser retries section by section, so the valid parts still render and the broken ones get an annotation showing the offending line.

TomlView(
  content: brokenToml,
  config: TomlViewerConfig(
    showInlineErrors: true,   // the banner and inline annotations
    maxRenderedErrors: 50,    // cap the widgets a pathological file can create
    onParseErrors: (errors) {
      for (final e in errors) {
        debugPrint('Line ${e.line}:${e.column} — ${e.message}');
      }
    },
  ),
)

Duplicate keys — which TOML forbids — are reported rather than silently resolved.

How it works #

Worth understanding if you're rendering large files, or wondering why there's a node model in the public API.

The important part is that the widget never builds a nested widget tree. It flattens the document into the list of rows that are currently visible and hands that to a SliverList.builder. Three consequences:

Parsing over 50 KB is moved to a background isolate automatically, so a large file doesn't jank the frame it loads on.

These aren't claims in a README — they're assertions in test/toml_lazy_rendering_test.dart.

Anatomy of a row #

Where to look when you want to change how something appears.

Configuration reference #

TomlViewerConfig #

TomlViewerColors #

value · type · symbol · nonRootKey · rootKey · tableKey · arrayIndex · arrayExpandable · errorHighlight · errorText · searchHighlight · lineNumber

Presets: TomlViewerColors.light, .dark, .of(context).

TomlViewerStyle #

Presets: TomlViewerStyle.fallback, .monospace, and the .monospaceFallback font stack.

TomlView #

Beyond the source and config: mode, searchQuery, caseSensitiveSearch, expandController, padding, shrinkWrap, physics, scrollController, loadingBuilder, errorBuilder, emptyBuilder.

Working with the parsed tree #

The node model is public, so the parsed document is yours to walk — useful for exports, validation, or building a completely different UI on the same data.

final result = await TomlParser.parse(tomlText);
final root = TomlNode.root(result.data!);

void visit(TomlNode node) {
  print('${'  ' * node.depth}${node.path}: ${node.typeName}');
  for (final child in node.children) {
    visit(child);
  }
}
visit(root);

TomlNode is a sealed class — TomlLeafNode, TomlTableNode, and TomlArrayNode — so a switch over it is exhaustive:

final label = switch (node) {
  TomlLeafNode(:final value) => 'leaf: $value',
  TomlTableNode(:final table) => 'table of ${table.length}',
  TomlArrayNode(:final list) => 'array of ${list.length}',
};

The same flattening the widget uses is exported too:

final rows = flattenVisible(root, isExpanded: (_) => true, query: 'host');

Public API #

FAQ and troubleshooting #

config.copyWith(style: config.style.clear(maxValueLines: true))

final saved = controller.overrides;   // Map<String, bool>, ready for JSON
controller.restore(saved);

Upgrading from 1.x #

The CHANGELOG has the full list. The three changes most likely to touch your code:

// 1. Colours moved into TomlViewerColors.
TomlViewerConfig(valueColor: Colors.red)                              // before
TomlViewerConfig(colors: TomlViewerColors(value: Colors.red))         // after

// 2. TomlViewerConfig.of takes only a context; chain copyWith for the rest.
TomlViewerConfig.of(context, expandMode: false)                       // before
TomlViewerConfig.of(context).copyWith(expandMode: false)              // after

// 3. TomlViewerTheme no longer takes a separate style.
TomlViewerTheme(config: c, style: s, child: v)                        // before
TomlViewerTheme(config: c.copyWith(style: s), child: v)               // after

The old colour getters (valueColor, keyColor, …) still work for reads; they are deprecated and will be removed in 3.0.0.

Try the example app #

git clone https://github.com/sudhi001/toml_viewer
cd toml_viewer/example
flutter run

Eight tabs, one per feature: search and source, asset loading, inline strings, maps, error handling, the expand controller, custom styling, and builders.

Requirements #

• Dart SDK >=3.6.0 <4.0.0
• Flutter >=3.27.0 — Color.withValues and Color.r/g/b are used throughout and arrived in that release
• Platforms Android · iOS · Linux · macOS · Web · Windows
• Dependencies just toml

Contributing #

Contributions are welcome — see CONTRIBUTING.md.

dart format .
flutter analyze --fatal-infos     # zero issues expected
flutter test                      # 141 tests
flutter test --tags golden        # 7 golden tests, generated on macOS

CI runs all of the above, plus the example app and a pub publish --dry-run. The demo GIF and the diagrams above are generated, not hand-drawn:

./tool/make_gif.sh                # renders frames from the widget, encodes the GIF
python3 tool/make_diagrams.py     # emits the light and dark SVG pairs

Bugs or requests #

Open an issue. Minimal reproductions are gratefully received.

License #

MIT — see LICENSE.

Author #

Sudhi S — GitHub · support@sudhi.in