CSS float · crash-free selection · AI/LLM streaming · CJK/Furigana · @keyframes · 2 490+ tests · XSS-safe · Zero Gradle config

Live Web Playground · Quick Start · AI Streaming · 30s Migration · Why Switch? · API · Packages

⚡ 30-Second Drop-in Migration from flutter_html

// 1. In your pubspec.yaml:
// dependencies:
//   hyper_render: ^1.13.1

// 2. In your Dart file — replace this single line:
// ❌ import 'package:flutter_html/flutter_html.dart';
import 'package:hyper_render/compat/flutter_html.dart';

// 3. Your existing code works out of the box — rendered by one RenderObject
//    instead of hundreds of nested widgets (see "Why Switch?" below).
Html(
  data: '<h1>Hello</h1><p>Text wraps seamlessly around floats!</p>',
  onLinkTap: (url, attributes, element) => launchUrl(Uri.parse(url!)),
)

Demos

🚀 Quick Start

dependencies:
  hyper_render: ^1.13.1

import 'package:hyper_render/hyper_render.dart';

HyperViewer(
  html: articleHtml,
  onLinkTap: (url) => launchUrl(Uri.parse(url)),
)

🤖 AI / LLM Real-Time Streaming

final controller = HyperStreamingController();

// Bind directly to any Dart Stream (e.g. OpenAI / Gemini SDK):
controller.bindStream(aiTokenStream);

// Render with automatic stick-to-bottom auto-scroller and pulsing caret:
HyperViewer.streaming(
  streamingController: controller,
  contentType: HyperContentType.markdown,
  showTypingCaret: true,
  caretStyle: HyperTypingCaretStyle.bar,
  autoRepairSyntax: true,   // Auto-closes incomplete ```, **, $$, | on the fly
  autoScrollToBottom: true, // Smoothly tracks stream tail
)

🏗️ Why Switch? The Architecture Argument

Feature Matrix

Benchmarks

Features

CSS Float — Magazine Layouts

HyperViewer(html: '''
  <article>
    <img src="photo.jpg" style="float:left; width:180px; margin:0 16px 8px 0; border-radius:8px;" />
    <h2>The Art of Layout</h2>
    <p>Text wraps around the image exactly like a browser — because HyperRender
    uses the same block formatting context algorithm.</p>
  </article>
''')

Crash-Free Text Selection

HyperViewer(
  html: longArticleHtml,
  selectable: true,
  showSelectionMenu: true,
  selectionHandleColor: Colors.blue,
)

CJK Typography — Ruby / Furigana

HyperViewer(html: '''
  <p style="font-size:20px; line-height:2;">
    <ruby>東京<rt>とうきょう</rt></ruby>で
    <ruby>日本語<rt>にほんご</rt></ruby>を学ぶ
  </p>
''')

CSS Variables · Flexbox · Grid

HyperViewer(html: '''
  <div style="display:flex; flex-wrap:wrap; gap:14px;">
    <div style="flex:1 1 220px; min-width:220px;">Card 1</div>
    <div style="flex:1 1 220px; min-width:220px;">Card 2</div>
    <div style="flex:1 1 220px; min-width:220px;">Card 3</div>
  </div>
''')

HyperViewer(html: '''
  <style>
    :root { --brand: #6750A4; --surface: #F3EFF4; }
  </style>
  <div style="display:grid; grid-template-columns:1fr 1fr; gap:12px;">
    <div style="background:var(--brand); color:white; padding:16px; border-radius:12px;">
      Column one — themed with CSS custom properties
    </div>
    <div style="background:var(--surface); padding:16px; border-radius:12px;">
      Column two — same token system
    </div>
  </div>
''')

HyperViewer(
  html: '<p>Themed text</p>',
  customCss: ':root { --brand: #6750A4; } p { color: var(--brand); padding: calc(8px * 2); }',
)

DevTools — Inspect, Profile, Live-Edit

void main() {
  assert(() { HyperRenderDevtools.register(); return true; }()); // debug only
  runApp(const MyApp());
}

Dark Mode

// A surface that stays light under a dark theme (an email pane, a paper page):
HyperViewer(html: html, textColor: Colors.black87)

CSS @keyframes Animation

<style>
  @keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
  @keyframes slideUp { from { transform: translateY(24px); opacity: 0; }
                       to   { transform: translateY(0);    opacity: 1; } }
  @keyframes flash  { from { background-color: #fffbdd; } to { background-color: #ffffff; } }
  .hero { animation: fadeIn 0.6s cubic-bezier(0.4, 0, 0.2, 1); }
  .card { animation: slideUp 0.4s ease-out; }
  .tick { animation: flash 1s steps(4, end); }
</style>
<div class="hero"><h1>Welcome</h1></div>
<div class="card"><p>Animated without any Dart code.</p></div>

XSS Sanitization — Safe by Default

// Safe — strips <script>, on* handlers, javascript: URLs
HyperViewer(html: userGeneratedContent)

// Custom allowlist for stricter sandboxing
HyperViewer(html: userContent, allowedTags: ['p', 'a', 'img', 'strong', 'em'])

// Disable only for fully trusted, internal HTML
HyperViewer(html: trustedCmsHtml, sanitize: false)

Multi-Format Input

HyperViewer(html: '<h1>Hello</h1><p>World</p>')
HyperViewer.delta(delta: '{"ops":[{"insert":"Hello\\n"}]}')
HyperViewer.markdown(markdown: '# Hello\n\n**Bold** and _italic_.')

Screenshot Export

final captureKey = GlobalKey();
HyperViewer(html: articleHtml, captureKey: captureKey)

// Export to PNG bytes
final png = await captureKey.toPngBytes();
final hd  = await captureKey.toPngBytes(pixelRatio: 3.0);

Hybrid WebView Fallback

HyperViewer(
  html: maybeComplexHtml,
  fallbackBuilder: (context) => WebViewWidget(controller: _webViewController),
)

📖 API Reference

HyperViewer

HyperViewer({
  required String html,
  String? baseUrl,           // resolves relative <img src> and <a href>
  String? customCss,         // lower priority than the document's own <style> tags (they win at equal specificity; use !important to force)
  Color? textColor,          // document text color; wins over html/body/:root color, not over element colors
  bool selectable = true,
  bool sanitize = true,
  List<String>? allowedTags,
  HyperRenderMode mode = HyperRenderMode.auto, // sync | virtualized | paged | auto
  bool enableZoom = false,
  void Function(String)? onLinkTap,
  HyperWidgetBuilder? widgetBuilder,           // custom widget injection
  WidgetBuilder? fallbackBuilder,
  WidgetBuilder? placeholderBuilder,
  GlobalKey? captureKey,
  bool showSelectionMenu = true,
  String? semanticLabel,
  HyperViewerController? controller,
  HyperPageController? pageController,         // paged mode only
  HyperPluginRegistry? pluginRegistry,         // custom tag plugins
  void Function(Object, StackTrace)? onError,
})

HyperViewer.delta(delta: jsonString, ...)
HyperViewer.markdown(markdown: markdownString, ...)

HyperRenderMode

HyperPageController (paged mode)

final ctrl = HyperPageController();

HyperViewer(html: html, mode: HyperRenderMode.paged, pageController: ctrl)

ctrl.nextPage(duration: Duration(milliseconds: 300), curve: Curves.easeInOut);
ctrl.animateToPage(2, duration: Duration(milliseconds: 300), curve: Curves.easeInOut);
ctrl.jumpToPage(0);

// Reactive page indicator:
ValueListenableBuilder<int>(
  valueListenable: ctrl.currentPage,
  builder: (_, page, __) => Text('Page ${page + 1} of ${ctrl.pageCount}'),
)

Plugin API — Custom HTML Tags

class MyCardPlugin implements HyperNodePlugin {
  @override String get tagName => 'my-card';
  @override bool get isInline => false;

  @override
  Widget? build(HyperPluginBuildContext ctx) {
    return Card(child: Text(ctx.node.textContent));
    // Return null to fall through to default rendering.
  }
}

final registry = HyperPluginRegistry()..register(MyCardPlugin());
HyperViewer(html: '<my-card>Hello</my-card>', pluginRegistry: registry)

HyperViewerController

final ctrl = HyperViewerController();
HyperViewer(html: html, controller: ctrl)

ctrl.scrollToId('section-2');   // scroll to <id="section-2">
ctrl.scrollToOffset(1200);        // absolute pixel offset

Custom Widget Injection

HyperViewer(
  html: html,
  widgetBuilder: (node) {
    if (node is AtomicNode && node.tagName == 'iframe') {
      return YoutubePlayer(url: node.attributes['src'] ?? '');
    }
    return null; // fall back to default rendering
  },
)

HtmlHeuristics — Introspect Before Rendering

if (HtmlHeuristics.isComplex(html)) {
  // use HyperRenderMode.virtualized for long documents
}
HtmlHeuristics.hasComplexTables(html)
HtmlHeuristics.hasUnsupportedCss(html)
HtmlHeuristics.hasUnsupportedElements(html)

Architecture

HTML / Markdown / Quill Delta
          │
          ▼
   ADAPTER LAYER         HtmlAdapter · MarkdownAdapter · DeltaAdapter
          │
          ▼
  UNIFIED DOCUMENT TREE  BlockNode · InlineNode · AtomicNode
                         RubyNode · TableNode · FlexContainerNode · GridNode
          │
          ▼
    CSS RESOLVER          specificity cascade · var() · calc() · inheritance
          │
          ▼
  SINGLE RenderObject     BFC · IFC · Float · Flexbox · Grid · Table
                          Canvas painting · continuous span tree
                          Kinsoku · O(log N) binary-search selection

When NOT to Use

♿ Accessibility (WCAG 2.1 AA)

<img src="chart.png" alt="Q3 revenue chart — $2.4M, up 18% YoY">
<a href="/privacy" aria-label="Privacy policy (opens in new tab)">Privacy</a>

📦 Packages

Optional add-ons

hyper_render_epub — EPUB 2/3 Reader Container

dependencies:
  hyper_render_epub: ^0.1.3

import 'package:hyper_render_epub/hyper_render_epub.dart';

// 1. Open the .epub (any Uint8List: File, asset, network)
final book = await EpubBook.open(epubBytes);

// 2. A controller holds the position; dispose() it when done
final controller = EpubReaderController(book: book);

// 3. Render the current chapter; drive next()/previous()/goTo() from your own UI
EpubReader(
  controller: controller,
  textColor: null, // null follows the theme; set it for a sepia/paper page
)

hyper_render_clipboard — Native image copy / share

dependencies:
  hyper_render_clipboard: ^1.7.3

import 'package:hyper_render_clipboard/hyper_render_clipboard.dart';

// HyperViewer has no clipboard parameter: hand images to HyperImage yourself.
HyperViewer(
  html: html,
  widgetBuilder: (node) {
    if (node is AtomicNode && node.tagName == 'img' && node.src != null) {
      return HyperImage(src: node.src!, clipboardHandler: SuperClipboardHandler());
    }
    return null;
  },
)

hyper_render_math — LaTeX / MathML rendering

dependencies:
  hyper_render_math: ^1.7.0

import 'package:hyper_render_math/hyper_render_math.dart';

final registry = HyperPluginRegistry()..register(const MathPlugin());
HyperViewer(html: html, pluginRegistry: registry)

Contributing

git clone https://github.com/brewkits/hyper_render.git
cd hyper_render
flutter pub get
flutter test
dart format --set-exit-if-changed .
flutter analyze --fatal-infos

License

pub.dev · API docs · Changelog · Roadmap