Welcome to Vanilla Breeze
This bell pulls live notifications from /go/notify/messages — the same contract documented at /docs/concepts/service-contracts/. Static articles like this one are the no-JS / no-backend fallback.
data-highlights
Medium-style text highlighting and annotation with color swatches, private notes, and localStorage persistence.
Overview
The data-highlights attribute enables Medium-style text selection highlighting on any element. Users can select text, choose a highlight color, add private notes, and all annotations persist in localStorage.
Uses the CSS Custom Highlight API for non-destructive rendering, with a <mark> wrapping fallback for older browsers.
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
data-highlights |
string (optional) | pathname | Enables highlighting. Optional value becomes the localStorage key suffix. |
data-highlights-colors |
comma-separated | yellow,green,blue,pink |
Available highlight colors. Maps to --highlight-{color} CSS tokens. |
data-highlights-readonly |
boolean | — | Renders stored highlights but disables creating new ones. |
Basic Usage
Add data-highlights to any content container. Users can select text to see a color-swatch toolbar.
Enable highlighting
<article data-highlights> <h2>Article Title</h2> <p>Select any text in this article to highlight it. Highlights persist in localStorage.</p></article>Custom Colors
Override the default palette with data-highlights-colors.
Custom color palette
<article data-highlights data-highlights-colors="yellow,pink"> <p>Only yellow and pink swatches will appear.</p></article>Define the actual color values with CSS custom properties:
Custom highlight colors
:root { --highlight-yellow: #fef08a; --highlight-green: #bbf7d0; --highlight-blue: #bfdbfe; --highlight-pink: #fbcfe8; /* Add your own: */ --highlight-orange: #fed7aa;}Custom Storage Key
By default, highlights are stored per page pathname. Provide a value to use a custom key.
Custom storage key
<article data-highlights="my-notes"> <p>Uses localStorage key: vb-highlights:my-notes</p></article>Read-Only Mode
Render previously stored highlights without allowing new ones.
Read-only highlights
<article data-highlights data-highlights-readonly> <p>Highlights are visible but users cannot create new ones.</p></article>Private Notes
Click an existing highlight to open the toolbar, then click “Add Note” to attach a private note. Notes appear as Medium-style margin annotations on wide screens and as a fixed bottom panel on narrow screens.
Notes are stored alongside highlights in localStorage. The note panel supports Ctrl+Enter to save and Esc to cancel.
How It Works
- On page load,
highlights-init.jsfinds all[data-highlights]elements and creates aHighlightControllerfor each. - When text is selected (via
pointerup), a color-swatch toolbar appears as a popover above the selection. - Clicking a color creates a highlight stored as text offsets in localStorage, with a content hash for drift detection.
- The CSS Custom Highlight API renders highlights non-destructively (no DOM mutation). On unsupported browsers,
<mark>elements are inserted as a fallback. - A
MutationObserverwatches for dynamically added[data-highlights]elements.
JavaScript API
Access the controller programmatically:
Programmatic API
import { initHighlights } from './utils/highlights-init.js'; const article = document.querySelector('article');const controller = initHighlights(article); // Get all highlightsconst highlights = controller.getHighlights(); // Remove a specific highlightcontroller.removeHighlight(highlights[0].id); // Clear allcontroller.clearAll(); // Export/importconst json = controller.exportHighlights();controller.importHighlights(json); // Cleanupcontroller.destroy();Events
| Event | Detail | Description |
|---|---|---|
highlights:added |
{ id, text, color, note } |
Fired when a new highlight is created |
highlights:removed |
{ id } |
Fired when a highlight is deleted |
highlights:clicked |
{ id } |
Fired when a highlight is clicked |
highlights:note-changed |
{ id, note } |
Fired when a note is saved |
Accessibility
- Toolbar uses
role="toolbar"with arrow-key navigation between color swatches - Screen reader announcements via
aria-live="polite"region - Keyboard: Escape closes toolbar, Ctrl+Enter saves notes
- Color swatches use
aria-labelwith color names andaria-pressedfor active state - Note panel uses
role="dialog"witharia-label
CSS Tokens
| Token | Default | Description |
|---|---|---|
--highlight-yellow | #fef08a | Yellow highlight color |
--highlight-green | #bbf7d0 | Green highlight color |
--highlight-blue | #bfdbfe | Blue highlight color |
--highlight-pink | #fbcfe8 | Pink highlight color |
Related
- article — Common container for highlights
- mark — Native highlight element (used as fallback)
- text-reader — Text-to-speech with word highlighting