Highlights

The Review Interface supports three highlighting approaches. Most extension authors will use transient highlights or the Content Highlighting Framework depending on their use case. Persistent highlight management is a separate feature with a narrower purpose.

---

Choosing an approach

Use the Content Highlighting Framework when:

• You want the framework to manage the highlight lifecycle for you — it handles invoking your render function per document per viewer type, cancellation, cross-viewer visibility sync, per-document caching, and card integration
• You need a sidebar card that stays in sync with the rendered highlights (the framework solves the "late-open" problem for you)
• You need highlights to render consistently across multiple viewer types with shared visibility state
• Examples: AI-for-Review features, entity extraction overlays, custom search term highlighting, document analytics

Use Transient Highlights when:

• You need direct control over when and how highlights are created — for example, in response to user actions or events rather than on document load
• You want to allow users to draw, move, or delete highlights interactively
• The Content Highlighting Framework's render function model doesn't fit your use case
• Examples: user-drawn redactions, annotation tools, selection-based markup, event-driven highlighting

Both approaches can be backed by API calls. The Content Highlighting Framework provides a lot of infrastructure you'd otherwise need to build yourself on top of transient highlights — render function invocation, cancellation, caching, cross-viewer sync, and card lifecycle management. If you need that infrastructure, use the framework. If you need more direct control or have simpler requirements, transient highlights give you a lower-level API.

---

Persistent Highlighting

IViewerHighlightManager (accessible via api.viewer.mainCollection.activeViewer?.persistentHighlight) is specifically for interacting with Relativity's built-in Persistent Highlighting feature — reading and applying saved highlight sets defined in the workspace. It is not intended as a general-purpose highlighting API for extensions building custom highlighting behavior. Use transient highlights or the Content Highlighting Framework for that instead.

---

Summary

	Content Highlighting Framework	Transient Highlights	Persistent Highlighting
Render function lifecycle managed	Yes	No	No
User-interactive (draw/move/delete)	No	Yes	No
Cross-viewer visibility sync	Yes (built-in)	Manual	Yes
Sidebar card support	Yes (built-in)	Manual	No
Per-document caching	Yes (built-in)	Manual	No
Use in extensions	Yes	Yes	Read-only access