Flutter HTML Viewer #

A Flutter package for displaying HTML content with highlights, selection controls, and customizable UI for note-taking or annotations. This library started as a "book reader" approach, but has now been refactored into a generic HTML reading solution where references to books have been replaced by a single metaData field.

Key Features #

• Render HTML: Supports parsing basic HTML tags (b, i, u, a, hr, br, etc.) into Flutter InlineSpans.
• Highlight Text: Allows applying highlights (with customizable colors) to any portion of the displayed text.
• Notes / Annotations: You can attach notes to highlighted sections, which appear underlined if present.
• Custom Selection Toolbar: A fully customizable CustomTextSelectionControls that provides search actions, highlight button, copy & share, and a button to add notes.
• RTL/LTR Support: You can set TextDirection for your entire HTML content.
• Pluggable Highlight UI: By default, a HighlightBottomSheet is provided, but you can replace it with your own UI via highlightSheetBuilder or onHighlightRequested.
• Metadata: A single metaData field allows you to pass any extra data (e.g., doc info, user info) without referencing a specific "book" concept.

Quick Example #

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

void main() {
  runApp(const MyExampleApp());
}

class MyExampleApp extends StatelessWidget {
  const MyExampleApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'flutter_html_viewer Example',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: const MyExampleHomePage(),
    );
  }
}

class MyExampleHomePage extends StatelessWidget {
  const MyExampleHomePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Define custom text selection controls
    final selectionControls = CustomTextSelectionControls(
      metaData: {'title': 'My Document'},
      pageNumber: 1,
      fullPageText: "<p>Hello <b>World</b> from example!</p>",
      onHighlightDone: () => print("Highlight done!"),

      // Example search callbacks
      onSearchInContent: (text) => print("Search in Content: $text"),
      onSearchInGoogle: (text) => print("Search in Google: $text"),
      onSearchInDictionary: (text) => print("Search in Dictionary: $text"),
      onSearchInBing: (text) => print("Search in Bing: $text"),

      // If you want to replace the default bottom sheet with your own:
      // highlightSheetBuilder: (ctx, request) {
      //   return MyCustomHighlightSheet(request: request);
      // },

      // Or handle highlight entirely yourself:
      // onHighlightRequested: (request) {
      //   // showDialog(...) or any custom approach
      // },
    );

    return Scaffold(
      appBar: AppBar(title: const Text("HTML Viewer Example")),
      body: HtmlViewer(
        metaData: {'title': 'My Document'},
        pageNumber: 1,          
        htmlContent: "<h1>Hello <em>World</em></h1><p>This is a sample HTML content.</p>",
        fontFamily: 'Arial',
        fontSize: 16,
        textColor: Colors.black,
        lineHeight: 1.5,
        backgroundColor: Colors.white,
        textAlign: TextAlign.left,
        context: context,
        selectionControls: selectionControls,
        searchHighlights: [],
        userHighlights: [],
        onLinkTap: (url) => print("Link tapped: $url"),
        textDirection: TextDirection.ltr,
      ),
    );
  }
}

Main Classes #

1. HtmlViewer
   Core widget that displays HTML content, applies highlights, and hooks in custom selection controls.

2. CustomTextSelectionControls
   A subclass of MaterialTextSelectionControls that adds extra toolbar items (search, highlight, share, etc.) and the logic to show bottom sheets or dialogs for highlights.

3. HighlightBottomSheet
   The default bottom sheet UI for highlight color selection and note-taking. You can replace it by providing a highlightSheetBuilder or onHighlightRequested.

4. HighlightRange
   A simple model representing the start/end index of a highlight, along with color and note text.

5. HighlightRequest
   A data model used when you tap "Highlight" in the selection toolbar. Contains metaData, pageNumber, the selected text, etc. so your custom UI can handle it.

Parameters for HtmlViewer #

Parameters for CustomTextSelectionControls #

How Highlighting Works #

1. Selecting Text
   The user taps and holds on the text, then drags to select. The custom selection toolbar (provided by CustomTextSelectionControls) appears.

2. Pressing "Highlight"

   • By default, it calls the logic in custom_text_selection_controls.dart which will either:
     1. Call onHighlightRequested if defined, letting you handle everything yourself.
     2. Call highlightSheetBuilder if provided, letting you build a custom UI (e.g., a bottom sheet).
     3. Otherwise, show the default HighlightBottomSheet.

3. HighlightBottomSheet

   • Allows picking a highlight color and adding an optional note.
   • On saving (onSaved callback), the highlight is stored or processed in your DB/model (you can customize).

4. Re-rendering

   • The library merges userHighlights with searchHighlights to highlight text. If you want new highlights to appear, you need to update these lists and rebuild HtmlViewer.

Customizing or Replacing the Bottom Sheet #

• Using highlightSheetBuilder

  CustomTextSelectionControls(
    metaData: {...},
    pageNumber: 1,
    fullPageText: "...",
    onHighlightDone: () => print("Done"),
    onSearchInContent: (text) => print("Search in Content: $text"),
    onSearchInGoogle: (text) => print("Search in Google: $text"),
    onSearchInDictionary: (text) => print("Search in Dictionary: $text"),
    onSearchInBing: (text) => print("Search in Bing: $text"),
    highlightSheetBuilder: (ctx, request) {
      return MyOwnBottomSheetUI(request: request);
    },
  );
  

• Using onHighlightRequested

  CustomTextSelectionControls(
    metaData: {...},
    pageNumber: 1,
    fullPageText: "...",
    onHighlightDone: () => print("Done"),
    onSearchInContent: (text) => print("Search in Content: $text"),
    onSearchInGoogle: (text) => print("Search in Google: $text"),
    onSearchInDictionary: (text) => print("Search in Dictionary: $text"),
    onSearchInBing: (text) => print("Search in Bing: $text"),
  
    onHighlightRequested: (request) {
      // Show your own dialog, or do any custom flow
      showDialog(
        context: context,
        builder: (ctx) => AlertDialog(
          title: const Text("Your custom highlight UI"),
          content: Text("Selected text: ${request.selectedText}"),
          // ...
        ),
      );
    },
  );
  

In both methods, you gain full control over how the highlight is performed, stored, or presented to the user.

Example Project #

There's an example/ folder alongside this library that demonstrates how to integrate flutter_html_viewer in a real Flutter app. To try it:

1. Clone the repo.
2. cd example
3. flutter pub get
4. flutter run

You'll see a minimal Flutter app using HtmlViewer and custom text selection controls.

Contributing #

Contributions and pull requests are welcome! Please open an issue first to discuss the proposed changes. For major changes, please open a discussion or pull request early so we can coordinate.

License #

This project is licensed under the MIT License.