val_highlight

Syntax highlighting in pure Dart.

55 languages, incremental updates, themes, and HTML output.
Runs anywhere Dart runs: the VM, Flutter on every platform, and the web.

🦋 Flutter widgets · 💻 GitHub · 📦 pub.flutter-io.cn

✨ Why val_highlight? #

• Pure Dart — no native code, no WebView, no JavaScript. The same engine runs in Flutter apps, on servers, in command-line tools and on the web.
• Linear time — highlighting time grows in step with input size. On native code it averages about 43 MB/s across realistic sources; compiled to JavaScript, about 62 MB/s.
• Incremental — after an edit, only the lines it can affect are re-scanned: about 0.4 ms per keystroke in a 9,600-line file.
• Light — every language and theme is a separate const import, so an app ships only what it uses.
• Customisable — themes, grammars, renderers and detection can all be extended or replaced, with the same API the built-in languages use.
• Tested on real code — every grammar has reviewed golden snapshots, edge-case tests and incremental fuzzing, and has been run over tens of thousands of real source files.

For Flutter, use val_highlight_flutter. It adds CodeView, CodeField and theme integration on top of this package.

🛠️ Quick start #

dart pub add val_highlight

import 'package:val_highlight/val_highlight.dart';
import 'package:val_highlight/languages/dart.dart';

final html = const Highlighter().toHtml(source, language: dartLanguage);

Pair the HTML with a theme's stylesheet:

import 'package:val_highlight/themes/light.dart';

final css = lightTheme.toCss(); // .vh { … } .vh .vh-keyword { … }

Or write inline styles, with no stylesheet:

final result = const Highlighter().highlight(source, language: dartLanguage);
final html = result.toHtml(const HtmlRenderer(theme: lightTheme, wrap: true));

🌐 Languages #

55 languages, plus a generic fallback and plain text:

Import one language with package:val_highlight/languages/<name>.dart (for example languages/kotlin.dart for kotlinLanguage), or all of them with languages/all.dart (allLanguages, allLanguagesRegistry()).

Each language knows its aliases (kt, c++, yml, …), file extensions and file names (Dockerfile, CMakeLists.txt, Podfile, …):

final registry = allLanguagesRegistry();
registry.lookup('kt');                   // kotlinLanguage
registry.forFileName('lib/main.dart');   // dartLanguage
registry.resolve('something-unknown');   // genericLanguage (the fallback)

Unknown languages. genericLanguage highlights code in any language reasonably: comments, strings, numbers, common keywords, types, calls and operators. It is the fallback of allLanguagesRegistry() for unknown names and Markdown fences.

Detection. const LanguageDetector().detect(code, allLanguages) guesses from the file name, a #! line, or the content.

🎨 Themes #

lightTheme, darkTheme, sepiaTheme, dimTheme, midnightTheme, forestTheme, highContrastLightTheme and highContrastDarkTheme, from package:val_highlight/themes/<name>.dart, or all of them with themes/all.dart (allThemes). Every colour meets WCAG AA contrast (4.5:1); the high-contrast themes meet 7:1.

Adjust a theme, or build one from scratch:

final mine = lightTheme.extend(
  styles: {Scopes.keyword: const Style(color: 0xFFE8590C, bold: true)},
);

Use an existing VS Code theme:

final theme = ValTheme.fromVsCodeJson(
  File('my-theme-color-theme.json').readAsStringSync(),
);

It reads the editor colours and tokenColors, matching TextMate scopes the way VS Code does. Comments and trailing commas are allowed.

🧩 Tokens and incremental updates #

A HighlightResult stores tokens as two flat integer lists that cover the whole source with no gaps. Each token carries a scope stack such as string > interpolation > number:

for (final token in result.tokens) {
  print('${token.scopes.join(' > ')}: ${token.text}');
}

// Per line, for renderers:
result.forEachSegment(line, (start, end, stack) { … });

For editors, IncrementalHighlighter keeps a document highlighted as it changes:

final document = IncrementalHighlighter(language: dartLanguage, text: source);
final updated = document.update(editedSource);

🔧 Changing a built-in language #

// Add or remove keywords; a word can also move to another scope.
final myDart = dartLanguage.withKeywords(
  add: {Scopes.typeBuiltin: ['Widget', 'BuildContext']},
  remove: ['get', 'set'],
);

// Put your own rules first; they win over the built-in ones.
final withTodos = dartLanguage.extend(
  rules: [const TokenRule(r'\bTODO\b', scope: 'todo')],
);

// Replace a named part of a grammar. `grammar.repository.keys` lists them.
final quiet = dartLanguage.extend(repository: {'numbers': []});

A new scope such as todo only needs a theme entry: lightTheme.extend(styles: {'todo': const Style(bold: true)}).

✍️ Writing a grammar #

Most grammars need no regular expressions. Building blocks cover what languages repeat:

import 'package:val_highlight/advanced.dart';

const iniLanguage = Grammar(
  name: 'ini',
  fileExtensions: ['ini'],
  rules: [
    LineComment(';'),
    LineComment('#', afterSpace: true),
    QuotedString('"'),
    Numbers(),
    KeywordRule({Scopes.literal: ['true', 'false', 'on', 'off']}),
    Operators('='),
  ],
);

Blocks are ordinary rules, so they mix freely with TokenRule, RegionRule (nested sections such as strings and comments) and IncludeRule (reusable rule lists). Extend BlockRule to make your own blocks.

The earliest match wins; among rules that match at the same position, the first one listed wins. grammar.validate() reports mistakes immediately.

More region options:

• endReferencesBegin: true lets \1–\9 in end stand for text that begin captured — heredocs, raw strings, Markdown fences.
• embed: grammar or embedCapture: n runs another language inside the region. The region's end closes it from any depth, the way </script> ends a script in a browser.
• Grammar(restartLine: …) tells incremental highlighting where it can safely restart when a rule reads more than one line ahead.

Keeping a grammar fast. Start patterns with something specific — a literal, a small character class, or ^ for line-start rules — rather than ., a negated class, or a lookbehind. On native platforms, most patterns run as small Dart matchers instead of the regular expression engine; results are identical either way.

⚡ Performance #

Measured on a MacBook, compiled to native code, best of several runs:

Across ten languages of realistic source, highlighting averages about 43 MB/s natively and about 62 MB/s compiled to JavaScript. One keystroke with IncrementalHighlighter in a 9,600-line file takes about 0.4 ms.

Built by Val #

val_highlight is part of Val, the live visual layer for AI agents.

💬 Community #

Issues and pull requests are welcome on GitHub; see the contributing guide. If the package helps your project, consider giving it a like on pub.flutter-io.cn or a star on GitHub.

📄 License #

BSD 3-Clause — see LICENSE.