html_highlighter
Persistent, multi-colour text highlighting for HTML shown in a
webview_flutter WebView. Users select text to highlight it, in any number of
highlights and colours. Tapping a highlight opens an "Add to notes" popup, and
a long-press (or right-click) removes it. Everything saves and restores as
JSON, colour included.
Drop it into any Flutter app that shows HTML in a WebView.
Source: github.com/anjaneykumar7/html_highlighter

On the web (plain JS, React, Next.js), use web/: the same
features and the same saved JSON, so highlights move between app and site.
Contents
- Platforms and setup
- Install
- How it works in one minute
- 1. Ready-made widget
- 2. Your own WebView: the bridge
- Turning things on and off
- Images, video and PDF
- Colours
- What gets saved
- Mouse / trackpad
- Known limitations
- Playground app and tests
- Web version
Platforms

The playground app: Android, the "Add to notes" popup on Android, iPhone, and iPad with the saved JSON.
| Platform | Status |
|---|---|
| iOS / iPadOS | Supported; tested on iPhone and iPad simulators with touch |
| macOS | Supported; tested with mouse and trackpad |
| Android | Supported; tested on an Android 35 emulator (Pixel 7) with touch |
| Web, Windows, Linux | Not supported by the Flutter package: webview_flutter can't run JavaScript or post messages back to Dart there. For web sites, use web/ |
HighlightHost lets you plug in your own renderer if you ever need another
platform.
Install
flutter pub add html_highlighter
The package depends on webview_flutter ^4.14.1.
Platform setup
iOS / iPadOS
- The WebView must own the long-press gesture. Otherwise native text
selection never starts and nothing can be highlighted; the page sees the
touch but logs "No range found".
HighlightableHtmlViewhandles this by default withdefaultHighlightGestureRecognizers(tap, long-press, drags, scale). If you pass your owngestureRecognizers, keepLongPressGestureRecognizerin it. If you build your ownWebViewWidget, pass the same set. - Recent Xcode versions need the iOS deployment target at 15.0 or higher
(
ios/PodfileandRunner.xcodeproj); the Flutter template uses 13.0.
macOS
-
A sandboxed macOS app shows a blank WebView unless it may make outgoing network connections. This applies even to local HTML. Add this to both
macos/Runner/DebugProfile.entitlementsandRelease.entitlements:<key>com.apple.security.network.client</key> <true/> -
Recent Xcode versions need the macOS deployment target at 12.0 or higher; the Flutter template uses 10.15.
-
WebViewController.setBackgroundColorisn't implemented on macOS.HighlightableHtmlViewignores that error; set your background inaddCss.
How it works in one minute
- Wrap each highlightable block of HTML in
highlightContainer(type:, id:, html:). A page can have any number of containers: a question, its explanation, article sections, all on one page if you like. Text outside containers can be selected but never highlighted, so put lists, tables, images and iframes inside one. - Images and iframes (a video, a PDF) can sit inside a container; the text around them highlights as usual. An iframe's own content is a separate document and can't be highlighted.
- One engine,
assets/highlighter.js, runs in the page. When the user highlights or removes something it sends the whole current list of highlights to Dart. - Each highlight (a "model") has an owner,
userType. Onlystudenthighlights are reported back and can be removed by the user. - Each model's
idis its container's DOM id (highlight-container--question-…), so you can tell where it lives.
1. Ready-made widget
HighlightableHtmlView(
body: highlightContainer(type: 'article', id: section.id, html: section.html),
highlightColor: const Color(0xFF86EFAC), // colour for new highlights
initialHighlights: savedModels, // List<Map<String, dynamic>>
onHighlightChanged: (change) => save(change.models),
onAddToNote: (note) => createNote(note.cleanHtml),
highlightingEnabled: canHighlight, // change any time
showAddToNote: notesEnabled, // change any time
addCss: '.menu { display: none; }',
addScripts: const [
'<script>console.log("ready");</script>', // a full block…
'window.myFlag = true;', // …or plain JS
],
onCreated: (controller, bridge) => _bridge = bridge, // for clear() etc.
);
| Option | Default | Notes |
|---|---|---|
body |
required | HTML inside <body>; must contain container(s) |
initialHighlights |
[] |
restored after load, each in its saved colour |
userType |
'student' |
owner stamped on restored highlights |
highlightColor |
null |
colour for new highlights; null = engine yellow, no color saved. Change any time |
highlightingEnabled |
true |
false: users can't create or remove highlights; existing ones stay and still open their popup. Change any time |
showAddToNote |
true |
false: tapping a highlight opens no "Add to notes" popup. Change any time |
onHighlightChanged / onAddToNote |
– | see What gets saved |
onCreated |
– | gets the WebViewController and HtmlHighlightBridge |
onLoaded / onLoadError |
– | page finished (after restore) / resource error |
addCss |
'' |
your CSS, after the default styles, e.g. '.menu { … }' |
addScripts |
[] |
your scripts, appended after the engine in order. Each entry is a full <script>…</script> block or plain JS (wrapped for you); blank entries are skipped |
head |
'' |
extra <head> markup (fonts, CDN scripts…) |
defaultStyles |
true |
includes highlightDefaultCss before addCss |
mouseSelection |
true |
includes the mouse shim |
gestureRecognizers |
defaultHighlightGestureRecognizers |
keep long-press on iOS |
restoreDelay |
800 ms | wait after load before restoring |
allowsInlineMediaPlayback |
true |
iOS / macOS: video plays inside the page instead of only fullscreen. Read once, when the WebView is created |
backgroundColor, loadingBuilder |
– | backgroundColor is ignored on macOS |
Changing body, head, addCss or addScripts reloads the page; the
switches and highlightColor apply without a reload.
Inside a Flutter scroll view, pass your own gestureRecognizers without the
drag recognizers so the outer view can scroll. Keep the long-press one.
2. Your own WebView: the bridge
Use this when you build the HTML yourself.
final controller = WebViewController()
..setJavaScriptMode(JavaScriptMode.unrestricted);
final highlights = HtmlHighlightBridge(controller);
// a. Register channels BEFORE loading the page.
await highlights.attach(
onHighlightChanged: (change) => save(change.models),
onAddToNote: (note) => createNote(note.cleanHtml),
);
// b. Engine and helper scripts go AFTER your highlight containers.
final engineJs = await HighlighterScripts.load();
await controller.loadHtmlString('''
<style>$highlightDefaultCss</style>
${highlightContainer(type: 'question', id: q.id, html: q.html)}
${highlightContainer(type: 'explanation', id: q.id, html: q.explanation)}
<script>$engineJs</script>
<script>$highlightColorLayerScript</script> <!-- per-highlight colours -->
<script>${HighlighterScripts.mouseSelectionShim}</script> <!-- mouse/trackpad -->
''');
// c. In onPageFinished (after a short delay):
await highlights.setHighlightColor(currentColor); // optional
await highlights.restore(savedModels);
Or let buildHighlightDocument(body:, engineJs:, head:, addCss:, addScripts:) build the full page in the right order: default CSS, your CSS,
the containers, the engine, the colour layer, the mouse shim, then your
scripts.
- Channels:
attachonly registers channels you pass a callback for (onHighlightChanged,onAddToNote,onRestoreStatus). Never also registerHighlightChangeChannel,AddToNoteChannelorHighlightChannelyourself (names inHighlightChannels). iOS and macOS throw on duplicate channel names; Android silently replaces the first. - Styles: the engine only adds a class (
highlight-text-student/highlight-text-admin). WithouthighlightDefaultCssits highlights are invisible (unless they have a per-highlight colour). It also defines.noselect, which the engine adds when highlighting is turned off. - Gestures: on iOS, give your
WebViewWidgetdefaultHighlightGestureRecognizers(see setup). - Bridge methods:
restore,setHighlightColor,setUserHighlightEnabled(bool),setAddToNoteVisible(bool),clear(),toggleStudyAssist(),runScript(js), and thecolorsbook.
Turning things on and off
| Widget option | Bridge method | Effect |
|---|---|---|
highlightingEnabled |
setUserHighlightEnabled(bool) |
Off: no creating or removing highlights (touch or mouse), container text can't be selected. Existing highlights stay and still open their popup when tapped |
showAddToNote |
setAddToNoteVisible(bool) |
Off: tapping a highlight shows nothing |
| – | clear() |
Removes every highlight from the page. Your saved list is untouched |
The widget re-applies both switches every time the page loads.
Images, video and PDF
Images and iframes can sit inside a container; the text around them highlights as usual, and their own content (an iframe is a separate document) can't be highlighted.
-
No highlights across media. A selection that contains or crosses an iframe, video, audio, image, SVG, canvas,
objectorembedis cleared as soon as it forms and never becomes a highlight. Select the text on one side of it instead. -
Images: put them in a
<figure>or<div>, not inside a<p>, or "Add to notes" HTML leaves them out. -
Video: give the iframe a small page holding
<video controls playsinline src="…">(an iframesrcdoc), and keepallowsInlineMediaPlaybackon (the default). An iframe whosesrcis the.mp4itself opens a bare media document that never started on iOS. -
PDF: iOS WKWebView doesn't draw a PDF inside an iframe. Give the iframe a page that renders the PDF with pdf.js instead. pdf.js fetches the file, so its server must allow cross-origin reads (CORS:
Access-Control-Allow-Origin). -
WebKit may hold off work in iframes that are off screen, so a PDF can render only when it scrolls into view.
example/lib/sample_content.dart has ready-to-copy videoFrame(url) and
pdfFrame(url) helpers (playground code, not package API).
Colours (per highlight)
Every highlight can have its own colour, stored in its model.
- Set the colour for new highlights with
highlightColor(widget) orbridge.setHighlightColor(color). Change it at any time; existing highlights keep theirs, so users can mix any number of colours. restore()re-applies each model'scolor. Models without one stay the engine's default yellow and are never recoloured.nullmeans the engine default yellow, and nocoloris saved.- Colours are CSS hex:
#RRGGBB, or#RRGGBBAAwith alpha. Convert withhighlightColorToCss(Color)andhighlightColorFromCss(String). - How it works: the engine knows nothing about colour, so a page-side colour
layer paints highlights by
commonId, and the bridge adds"color"to models. SeeCONTEXT.md.
What gets saved
HighlightChange.models is a list of maps:
{
"commonId": "ie878at3",
"id": "highlight-container--question-demo-q1",
"startOffset": 387,
"endOffset": 390,
"color": "#86EFAC",
"userType": "student"
}
| Field | Meaning |
|---|---|
commonId |
highlight id (random, per highlight) |
id |
container DOM id, highlight-container--<type>-<id> |
startOffset / endOffset |
character offsets into the container's text |
color |
optional; only when a colour was set |
userType |
owner (student, admin, ops) |
- Store the list as JSON and pass it back to
restore. - Each change message carries the whole current list, not a diff.
- Offsets only line up if the container's HTML hasn't changed.
restorestamps itsuserType(defaultstudent) on every model, so models saved without one still restore.
HighlightNoteRequest.cleanHtml is the selected HTML with highlight
backgrounds stripped, ready for a note.
Mouse / trackpad
The engine is touch-driven: a highlight starts on touchend and is removed by
a long-press. A mouse fires neither. HighlighterScripts.mouseSelectionShim
bridges this (touch input is ignored, so nothing fires twice):
- finish a left-button selection inside a container → highlight is created
- press and hold a highlight for 350 ms → highlight is removed
- right-click a highlight → removed (the engine's own handler, where the host delivers right-clicks)
HighlightableHtmlView and buildHighlightDocument add it by default.
Known limitations
- Whole-paragraph selections are ignored. A triple-click, or a drag to the very end of a paragraph, ends the selection at the start of the next element, and the engine treats that as empty. This is rare with touch selection.
- Restored highlights are drawn twice. The restore runs again after
150 ms, which nests duplicate spans. The saved models aren't duplicated and
solid colours look the same, but semi-transparent colours look darker.
restore(reapplyAfter:)changes the delay but can't turn the second pass off. - One popup rule for all containers. "Add to notes" shows for every
container, question ones included; turn it off with
showAddToNote. - Images inside
<p>are left out of note HTML. When building "Add to notes" HTML the engine drops any<img>or<p>whose parent is a<p>. Put images in a<figure>or<div>instead. - iOS won't draw a PDF in an iframe pointed straight at it, and an iframe
pointed straight at an
.mp4didn't play on the iOS simulator. See Images, video and PDF for the setup that works. - iOS: the first touch after an existing selection only dismisses it. If text is already selected (for example right after a highlight is created, or after the playground's self-test), iOS uses the next touch to clear that selection, so a long-press there may not create a highlight. Holding again works.
Playground app
example/ is a Flutter app (Android, iOS, macOS) for trying everything: one
page with question, explanation and article sections (lists, tables, an image,
and a playing video and a rendered PDF in iframes), a colour picker, the on/off switches,
clear(), notes, press-and-hold removal, "Reload page" to check restore, the
saved JSON, an event log, a JS console, and an addCss / addScripts demo
(which also logs whether each iframe loaded).
cd example
flutter run -d macos
flutter run -d <ipad-simulator-id> # iOS / iPadOS
flutter run -d macos --dart-define=SELF_TEST=true # automated check on start
The Self-test button (or SELF_TEST) runs these checks inside the real
WebView and prints SELFTEST … PASS/FAIL: create, colour, popup after create,
press-and-hold removal, a list item, a table cell, text next to an image and
text next to an iframe, and that a selection across an iframe is blocked. It
uses synthetic mouse events, so on iOS also try real
touch by hand. See example/README.md.
Logs: the page's console goes to the "JS console" panel and to stdout as
[js] …, and app events print as [event] …. On the iOS simulator the
flutter run output lags behind the app, so trust the in-app event log
when judging whether a tap worked.
Tests
flutter test # package
cd example && flutter test
See CONTEXT.md for how it works and AGENTS.md for rules when changing it.
Web version
web/ is a separate JavaScript module for web pages: a
framework-agnostic highlighter.js plus react.js (HighlightableHtml,
useHighlighter, "use client" for Next.js). It has every feature above
(colours, owners, the "Add to notes" popup, press-and-hold and right-click
removal, merging, restore, clear(), the on/off switches, the touch guard and
the no-selection-across-media rule) and saves the same JSON. It is
independent of the Flutter code: no Dart, no WebView. See its README.

Files: highlighter.js ·
react.js ·
Highlighter.css ·
highlighter.d.ts.
With a mouse, the web version also opens the popup on hover and removes a
highlight on click (popupOnHover, clickToRemove); taps behave as in
the app. The Flutter package doesn't have these (in the app a click opens the
popup).
cd web && npm install && npm test
License
MIT. See LICENSE.
Libraries
- html_highlighter
- Persistent text highlighting for HTML rendered inside a
WebView.