ComponentViewer

Overview

ComponentViewer is a jQuery plugin that opens attachments (images, video, audio, PDF, inline content, and more) in a shared full-screen overlay with a consistent header, footer, and toolbar. It is designed for feed- or post-style UIs where each container (e.g. a post or card) has its own set of items; the plugin is instantiated per container, and one global overlay is reused.

Features include:

• Multiple content types: image (with zoom/pan), video, audio, PDF, inline/code, error, HTML, and unsupported fallback
• Configurable toolbar with built-in Download and zoom, plus custom toolbarItems and onToolbar
• Optional poll UI (radio/checkbox) above the toolbar for items with pollOptionLabel
• Dark/light theme with optional theme toggle
• Optional WCAG behavior: focus trap, focus save/restore, ARIA dialog semantics
• Loop on/off, optional counter, adjacent image preload, overlay fullscreen, touch swipe nav / swipe-to-close
• Optional tooltips on controls (canShowTooltip), keyboard shortcuts popup (shortcutsPopup)

License: MIT

Demo

Try the plugin in your browser with the full example page. It includes all content types (image, video, audio, PDF, inline, error, HTML), toolbar customisation, themes, poll options, loop and counter options, and image failure handling.

Open index.html — open this file in a browser to see multiple demo cases. Use the programmatic API buttons at the bottom to open specific items (e.g. Case 1: Image, Case 2: PDF, Case 14: Invalid URL).

The example page uses jQuery 3.7, jPlayer, and PDF.js (loaded from CDN). Without jPlayer or PDF.js, the plugin falls back to native <video>/<audio> and an iframe for PDF; use your own minimal HTML page with only jQuery + the plugin to try that. For other jQuery or library versions, point your script tags at the builds you need and use the same index.html markup as a reference.

Getting Started

Installation

Required: jQuery (1.7+ or 2.x / 3.x).

Optional:

• jPlayer — for rich video/audio playback. If not loaded, the plugin falls back to native <video> / <audio>.
• PDF.js — for PDF rendering with page navigation, thumbnails, zoom, rotate. If not loaded, the plugin falls back to an iframe.

Include the plugin and stylesheet after jQuery:

<link rel="stylesheet" href="component-viewer.css" />
<script src="jquery.min.js"></script>
<!-- Optional: jPlayer, PDF.js -->
<script src="component-viewer.js"></script>

Quick start

1. Mark up your items with a common selector (default .cv-item) and use data-* for type, source, and title:

<div id="my-gallery">
  <a class="cv-item" data-type="image" data-title="Photo.jpg" href="https://example.com/photo.jpg">
    <img src="https://example.com/thumb.jpg" alt="" />
  </a>
  <div class="cv-item" data-type="pdf" data-title="Doc.pdf" data-src="https://example.com/doc.pdf" data-ext="PDF">PDF</div>
</div>

2. Initialize the viewer on the container:

$('#my-gallery').componentViewer({
  toolbar: { download: true, zoom: true },
  pdf: { workerSrc: 'path/to/pdf.worker.min.js' }
});

3. Click any item to open it in the overlay; use prev/next to move between items.

Minimal copy-paste example

Below is a single block you can drop into an HTML file to try the plugin immediately (ensure jQuery and the plugin scripts/styles are loaded):

<!-- HTML: one image item -->
<div id="minimal-demo">
  <a class="cv-item" data-type="image" data-title="Sample" href="https://picsum.photos/800/600">
    <img src="https://picsum.photos/200/150" alt="" />
  </a>
</div>

<script>
$('#minimal-demo').componentViewer({ toolbar: { download: true, zoom: true } });
</script>

Building with the plugin

To integrate ComponentViewer into your app:

1. Choose a container — e.g. the element that wraps one post or one set of attachments.
2. Ensure each clickable attachment is a direct or nested element matching selector (default .cv-item).
3. Provide item data — either via data-type, data-src / href, data-title, etc., or via the itemData callback for full control.
4. Call $(container).componentViewer(options) once per container. Each container gets its own list of items (all elements matching the selector inside it) and its own index; the overlay is shared.
5. Optional: Use onRender to render custom content and return a custom toolbar; use onToolbar to modify the built-in toolbar; use onDownload to customize download behavior.

File structure

The ComponentViewer project includes the following files:

component-viewer-v2/
├── component-viewer.js      # Plugin script (jQuery plugin, overlay, built-in renderers)
├── component-viewer.css     # Styles for overlay, header, stage, toolbar, carousel, etc.
├── documentation.html       # API documentation (this file)
├── index.html             # Full demo with all content types and options
└── README.md                # Project overview and usage

Options reference

All options are optional. Defaults are available at $.fn.componentViewer.defaults. Pass an object to componentViewer(options) to override.

Quick reference

One-line summary of the main options. See the tables below for types, defaults, and full descriptions.

General options

Each Description is a short bullet list for easier scanning.

RTL mode (isRTL)

Set isRTL: true to run the overlay in right-to-left mode (default is false for LTR).

When RTL is enabled, the plugin applies these behavior changes:

• Overlay direction: overlay/shell are rendered with RTL direction (dir="rtl" + RTL class).
• Navigation layout: prev/next controls and related directional UI are mirrored.
• Keyboard navigation: arrow mapping is mirrored (← moves next, → moves previous).
• Touch swipe navigation: horizontal swipe prev/next mapping is mirrored.
• Carousel behavior: strip direction and prev/next carousel control movement are mirrored.
• Directional tooltips/labels: carousel left/right tooltip/aria labels are adjusted for RTL semantics.

Example:

$('#post').componentViewer({
  isRTL: true,
  toolbar: { download: true, zoom: true }
});

Live demo: see index.html (Case 29 — RTL mode).

Minimize mode

Set minimize: { enabled: true } (or shorthand minimize: true) to enable minimize/restore UI.

• Minimize: collapses overlay content and shows a floating restore icon.
• Restore: returns to the active item/session without reopening from scratch.
• Hidden element fallback: if the active item's bound DOM node is hidden/detached while minimized, restore still renders from a captured snapshot of that item.
• Click another bound element while minimized: viewer auto-expands and opens the clicked element.

$('#post').componentViewer({
  minimize: { enabled: true },
  carousel: { enabled: true },
  toolbar: { download: true, zoom: true }
});

Live demo: see index.html (Case 30 — Minimize and restore).

PDF options

PDF zoom. The built-in PDF renderer provides zoom via the toolbar +/− buttons and a zoom preset dropdown (50%, 75%, 100%, 125%, 150%, 175%, 200%, 225%, 250%, and Auto Fit). The footer zoom slider is not shown for PDF items. When the user zooms, all pages (and the text layer) are re-rendered at the new scale, so text selection stays aligned with the visible content.

Page navigation. The current page indicator (e.g. 1 / 14) is click-to-edit: click the current page number, type a page number, then press Enter or blur the field to jump to that page; press Escape to cancel. Scroll-based page detection still updates the indicator when not editing.

PDF.js version compatibility. The plugin uses the core PDF.js API (getDocument, getPage, getViewport, render, getAnnotations) and renders annotations (links, highlights) via a custom overlay. It is compatible with PDF.js 2.2.x (e.g. 2.2.228) as well as 3.x. When pdf.annotations is true, the plugin uses pdfjsLib.Util.normalizeRect when available (e.g. in 3.x); for 2.2.x legacy builds where Util may not be exposed, an internal fallback is used so annotation rendering works without throwing. Render tasks and document loading use .promise when present, with a thenable fallback for older 2.x builds. Set pdf.workerSrc to the worker script that matches your PDF.js build (e.g. pdf.worker.min.js for 2.2.228).

Media (jPlayer)

Per-item override: set item.supplied (e.g. via itemData or data-supplied) to override the format for a single item.

Video HD quality

When a video item has an HD or high-quality source URL, you can show an HD button in the player. The user clicks it to switch playback to that source from the current timestamp, so playback continues smoothly without restarting.

Provide the HD URL in either way:

• item.hdUrl — Set via itemData (e.g. from a data-hd-url attribute). If set and valid, the HD button is shown.
• video.onGetHdUrl(item, viewer) — Callback that returns the HD URL for the given item, or null. Called when the user clicks HD; if it returns a valid URL, playback switches to that URL from the current position.

When the user clicks HD, the plugin pauses playback, gets the current time, loads the new source via jPlayer setMedia, then seeks to the saved time and resumes if the video was playing. The HD button is highlighted when HD content is playing; clicking it again (or pressing Q) switches back to the original quality. See index.html Case 8b for a working demo.

Video: canShowHDButton and beforeVideoPlay (jPlayer only)

These options apply only when the built-in video renderer uses jPlayer. If jPlayer is not available, the plugin uses a native <video> element instead; canShowHDButton and beforeVideoPlay are not called in that case.

video.canShowHDButton(item, viewer) — Optional. When item.hdUrl is set and passes the plugin’s URL safety check, you can hide or show the HD button based on your own rules (e.g. feature flag, entitlement). If you do not provide this callback, behavior is unchanged: the HD control is shown whenever an HD URL is available via item.hdUrl or onGetHdUrl (see above). The callback is not used when there is no item.hdUrl; in that case HD may still appear when only onGetHdUrl is used.

video.beforeVideoPlay(item, viewer, next, $stage) — Optional. Invoked the first time the user starts playback (play / big play), before jPlayer is initialized. The fourth argument $stage is the jQuery object for the overlay .cv-stage (the same as in onRender). You can append directly to $stage (or to a child such as $stage.find('.cv-video-wrap')) to show any markup or component, then call next() or next({}) when you are ready for jPlayer to start—typically after the user dismisses your UI or after an async check; remove your inserted nodes before calling next() if you do not want them to remain visible.

Alternatively, use the built-in gate (same idea as beforeOpen): next({ gateContent: { html: …, onProceed: function () { return { /* optional context */ }; } } }). The content is shown inside the video wrapper (class cv-video-gate). gateContent.html may be an HTML string, a jQuery collection, or a DOM node; include an element with data-cv-gate-proceed for the continue action. When the user activates it, onProceed runs, its return value is assigned to viewer._videoBeforePlayContext, the gate is removed, and jPlayer starts.

You must call next for playback to begin; if you never call it, the player will not initialize.

Inline code & syntax highlighting

These options apply to type: 'inline' items (source/code view). Content is taken from item.content or fetched from item.src. The built-in view adds line numbers and a Copy button unless you fully override rendering.

Data and callbacks

Accessibility (WCAG)

Carousel

When the carousel option is set to an object with enabled: true, a thumbnails button appears in the overlay header. Clicking it toggles a strip of thumbnails below the stage so users can jump to any item by clicking its thumbnail. This is useful when there are many attachments and you want a quick overview and navigation.

The strip shows several thumbnails at a time (e.g. 4 or 5 visible). When the number of items exceeds carousel.navThreshold, prev/next arrows appear on the strip to scroll. Video and audio items can show a custom thumbnail via thumbnailUrl (or data-thumbnail) with a play icon overlay; otherwise the filename or type label is shown.

Configuration

Behavior

• The carousel strip is hidden by default when the overlay opens; the user toggles it with the header thumbnails button.
• When the item count is less than or equal to carousel.navThreshold, the strip prev/next arrows are hidden because all thumbnails fit in view.
• Clicking a thumbnail scrolls the strip to keep the active item in view and updates the stage to that item.

Example:

$('#post').componentViewer({
  carousel: { enabled: true, navThreshold: 4 },
  toolbar: { download: true, zoom: true }
});

Stage only

When stageOnly.enabled is true, the overlay shows only the center stage (and optionally prev/next navigation). The header (title, counter, close, theme, fullscreen, carousel) and footer (toolbar, zoom) are hidden. The user can close with Escape or by clicking the backdrop (if overlayClose is true). This is useful for kiosk-style or distraction-free viewing.

When stageOnly.hideNavigation is true, the prev/next arrow buttons are also hidden. The user can still move between items using keyboard navigation (Left/Right arrow keys when keyboardNav is true).

Configuration

Behavior

• When stageOnly is enabled, the overlay shell gets the class cv-stage-only so that header and footer are hidden via CSS.
• If slideshow is also enabled and there is more than one item, the footer can still show the Play/Pause slideshow button (see Slideshow).
• With hideNavigation: true, keyboard prev/next (arrow keys) continue to work when keyboardNav is true.

Example:

$('#post').componentViewer({
  stageOnly: { enabled: true, hideNavigation: false },
  overlayClose: true,
  keyboardNav: true
});

Example with keyboard-only navigation (no prev/next buttons):

$('#post').componentViewer({
  stageOnly: { enabled: true, hideNavigation: true },
  overlayClose: true,
  keyboardNav: true
});

Slideshow

When the slideshow option is set to an object with enabled: true, the viewer can auto-advance to the next item after a fixed interval (or when video/audio playback ends). This is useful for hands-free browsing of multiple attachments. The slideshow only runs when there are at least two items.

A Play slideshow / Pause slideshow button is added to the toolbar when slideshow is enabled, unless hideSlideshowButton: true and autoStart: true (in that case the button is hidden and the slideshow runs automatically with no way to pause from the UI). When autoStart: true and the button is shown, it shows Pause slideshow initially. If autoStart: false, the button shows Play slideshow until the user starts it. Optionally set showProgress: true to display a progress bar in the footer that fills until the next slide (default is false).

Configuration

Note: The option is interval (seconds). There is no delay option (e.g. delay: 4000 is not supported; use interval: 4 for 4 seconds).

Behavior

• The slideshow timer is cleared when the user closes the overlay, or when they use prev/next/goTo (so manual navigation does not double-advance).
• When the user clicks Pause slideshow, the timer is cleared and the slideshow does not restart on subsequent item loads until they click Play slideshow.
• The Play/Pause button appears at the start of the toolbar (before type-specific items such as PDF page controls) and is styled compactly so it does not dominate the footer.

Example:

$('#post').componentViewer({
  slideshow: {
    enabled: true,
    interval: 5,
    autoStart: true,
    advanceMedia: 'interval',
    showProgress: false   // set true to show progress bar until next slide
  },
  toolbar: { download: true, zoom: true }
});

Poll options

When pollOption.enabled is true and an item has pollOptionLabel, a row appears above the toolbar with the label and a radio or checkbox (depending on pollOption.mode). Use this for polls where each option is an image or attachment. Set item.pollOptionSelected to true (e.g. via itemData) to show the option as already selected when the overlay opens; if not given, the option is not selected. pollOption.onSelect(item, selected, viewer, element) is called when the user toggles; selected is the new checked state; element is the DOM node for the .cv-item that produced the item (or null for items-only usage without item.$el). The poll row is hidden for HTML type and for image error (footer is hidden).

Configuration

Item fields

Attachment comment

When showAttachmentComment is true and an item has a non-empty item.comments array, a compact dark semi-transparent overlay is shown at the bottom of the stage (over the media), matching the style of LC-Lightbox: each comment can have title (bold), optional “by Author” line, dotted separator, and description text. A header button (comment icon) toggles visibility.

Only item.comments is supported: an array of objects { title?, author?, text }. For a single comment, pass an array with one object: item.comments = [{ title: '...', author: '...', text: '...' }]. Provide it via itemData or data-comments (JSON string). When there is more than one comment, the overlay shows prev/next arrows and a counter (e.g. “Comment 1 of 3”). The “by” label is localized via commentBy; counter and arrow labels use commentCounter, commentPrev, commentNext. When the option is false or item.comments is missing or empty, the toggle and panel are hidden.

Image extract-text (OCR overlay)

When toolbar.extractText is true and both canShowExtractText and extractText callbacks are provided, the plugin shows an "Extract text" toolbar button for image items where canShowExtractText(item, viewer) returns true. (By default toolbar.extractText is false.) Clicking the button calls extractText(item, viewer, doneCallback, errorCallback) and shows a circle loader over the stage. The host performs OCR (e.g. an API call) and invokes doneCallback(resp) on success (loader is removed and the overlay is rendered) or errorCallback(message) on failure (loader is removed and a strip message is shown with the given message).

Options

Response shape (resp)

The resp object passed to doneCallback must follow this structure:

{
  data: {
    lines: [
      // Each line is an array of word objects
      [
        { box: [[x0,y0], [x1,y1], [x2,y2], [x3,y3]], word: "Hello" },
        { box: [[x0,y0], [x1,y1], [x2,y2], [x3,y3]], word: "world" }
      ],
      // ... more lines
    ]
  }
}

Each word has a box array of four corner points (typically top-left, top-right, bottom-right, bottom-left) in OCR reference pixel space, and a word string. The plugin maps corners to an axis-aligned rectangle (order-independent) and scales to the displayed <img> (including object-fit: contain letterboxing).

If OCR ran on a larger original than the preview shown in the viewer, include data.imageWidth and data.imageHeight (or sourceWidth / sourceHeight, width / height) matching that coordinate system. If omitted, the plugin assumes coordinates match the image’s naturalWidth / naturalHeight, or infers a wider/taller reference when box coordinates exceed those dimensions.

Behavior

• When the user clicks "Extract text", a circle loader is shown over the stage until the host calls doneCallback or errorCallback.
• On success, the loader is removed and the overlay is positioned on top of the image with each word rendered as a highlighted, selectable span.
• On failure, the host calls errorCallback(message); the plugin removes the loader and shows a strip message with the given message.
• Clicking "Extract text" again while the overlay is visible removes it (toggle behavior).
• When the user zooms the image, the overlay is removed. The user can click "Extract text" again to re-fetch at the new zoom level.
• The overlay uses plugin-scoped CSS classes (.cv-extract-overlay, .cv-extract-layer, .cv-extract-word) and does not depend on any external stylesheet.

I18N

The toolbar button label uses the extractText key from defaultStrings (default: "Extract text"). Override it via $.fn.componentViewer.defaultStrings.extractText for your locale.

Item data

Each item is a plain object describing one attachment. When itemData is not provided, the plugin builds it from the matched element as follows:

The plugin also sets item.$el to the jQuery-wrapped element. Use itemData to return a custom object: the callback receives ($el, defaultItem); you can add or override properties on defaultItem and return it, or return a new object (e.g. from your API).

Content types

The plugin chooses a renderer in this order:

1. onRender(item, $stage, viewer) — If it appends to $stage, the built-in renderer is skipped. It may return { toolbar: [...], destroy: function() } to supply a custom toolbar and a cleanup function. See Callbacks (lifecycle) for the full onRender return shape and execution order.
2. Built-in by type — Based on item.type (default 'image').
3. Unsupported — If the stage is still empty, a "no preview" card is shown.

Built-in types

Markdown

The markdown type renders Markdown as HTML in the overlay. Use it for .md files or inline markdown content.

Item data

Content can come from:

• item.content — Inline markdown string (e.g. from data-content).
• item.src — URL or path to a .md file; the plugin fetches it and renders the response. Relative URLs (e.g. sample.md) are resolved against the current document. Files with .md extension default to type markdown when data-type is not set.

Parser

Include the open-source marked library for full CommonMark support:

<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>

If window.marked is not present, the plugin uses a minimal built-in parser (headings, bold, italic, code, links, line breaks).

Toggle raw/source view

Set markdown: { toggleRawView: true } (default false) to show a toolbar button that toggles between rendered Markdown and raw/source view (same line-numbered style as inline content). Useful for viewing the .md source without leaving the overlay. See index.html Case 5b.

Example

<!-- Inline content -->
<div class="cv-item" data-type="markdown" data-title="Note.md" data-content="# Hello\n**Bold** and *italic*.">Note</div>

<!-- Load from URL -->
<div class="cv-item" data-type="markdown" data-title="README.md" data-src="https://example.com/README.md">README</div>

Toolbar & image zoom

Footer toolbar controls (plus the separate image zoom widget) are configured with toolbar, zoom, and optional toolbarItems:

How the toolbar is resolved

The toolbar is resolved as follows:

• For html type: minimal toolbar — slideshow button when enabled; optional View Source / View Markdown toggle when toolbar.toggleSource is true, resolveMarkdownToggleUrl is set, and the item looks like markdown (e.g. .md) with iframe src; and Download when toolbar.download is not false and the item has a valid download URL (same rule as other types). Footer hidden if none of these apply (except slideshow progress bar can still keep the footer visible). For image error: no toolbar, footer hidden.
• When onRender returns a toolbar array: that array is used as-is (no auto download/zoom).
• Otherwise: renderer toolbar (if any) + toolbarItems (with optional separator) are merged; for inline type a Copy button is added (copies content to clipboard and shows "Copied to clipboard"); for markdown type with markdown.toggleRawView: true a View source / View as Markdown toggle is added; for image type when toolbar.extractText is true and canShowExtractText / extractText are provided, an Extract text button is added; then onToolbar can modify the array; then the Download button is appended when toolbar.download is not false and the item has a valid download URL. The zoom widget is shown for image items when toolbar.zoom is not false.

Ways to build the toolbar

The toolbar array can be built from multiple sources:

Toolbar entry types

Each element in a toolbar array can be one of:

Toolbar item object properties

When an entry is an object, the following properties are supported:

Example: custom toolbarItems shape

Pass an array of button objects, 'separator' (or '-'), and optionally DOM/jQuery nodes. Each button is a plain object; the plugin merges these entries with the built-in renderer toolbar (PDF controls, etc.) and may append Download after onToolbar runs.

$('#post').componentViewer({
  toolbar: { download: true, zoom: true },
  toolbarItems: [
    {
      id: 'share',
      label: 'Share',
      tooltip: 'Copy link to this attachment',
      // icon: Font Awesome class OR inline SVG (HTML string is sanitized)
      icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" fill="currentColor" aria-hidden="true"><path d="M11 2.5a2.5 2.5 0 1 1 .603 1.628l-6.718 3.12a2.5 2.5 0 0 1 0 1.504l6.718 3.12a2.5 2.5 0 1 1-.488.876l-6.718-3.12a2.5 2.5 0 1 1 0-3.256l6.718-3.12A2.5 2.5 0 0 1 11 2.5z"/></svg>',
      onClick: function (item, viewer) {
        var url = item.downloadUrl || item.src;
        if (url && navigator.clipboard) {
          navigator.clipboard.writeText(url);
          viewer.showStripMessage('Link copied');
        }
      }
    },
    'separator',
    {
      id: 'annotate',
      label: 'Note',
      showLabel: true,
      className: 'my-toolbar-note',
      // Only show for images (optional)
      visible: function (item /* , viewer */) {
        return item.type === 'image';
      },
      // Single letter; avoid reserved keys (Space, M, R, Q, D, P, F, T, C, S, ?, +, -, =, arrows, Esc)
      shortcutKey: 'n',
      onClick: function (item, viewer) {
        /* open your panel, track analytics, etc. */
      }
    }
  ]
});

Minimal variant (icon class + click handler only):

toolbarItems: [
  { id: 'share', icon: 'fa fa-share', label: 'Share', onClick: function (item, viewer) { /* ... */ } },
  'separator',
  { id: 'extra', label: 'Extra', shortcutKey: 'e', onClick: function (item, viewer) { /* ... */ } }
]

Keyboard shortcuts

When keyboardNav is true, the following shortcuts are available. Press ? (Shift+/) to open a popup that lists only the shortcuts enabled for the current item (by type and toolbar options).

Custom toolbar shortcuts: Add shortcutKey: 'e' (or any single character) to a toolbar item to give it a keyboard shortcut. That shortcut appears in the popup only when the button is visible. Reserved keys (Escape, arrows, Space, M, R, Q, D, P, F, T, C, S, ?, +, -, =) are not available for custom items.

Set shortcutsPopup: false to disable the ? popup.

I18N (Internationalization)

All user-facing text in the overlay (button labels, tooltips, error messages, and type labels) comes from a single default string registry defined inside the plugin. The plugin never uses hardcoded strings; it looks up every label by key from this registry. This lets you localize the UI by replacing the registry with your own translations.

For Japanese (日本語) UI, ship or build a copy of the plugin with Japanese defaultStrings (see component-viewer-japanese.js in the repo if present), or set $.fn.componentViewer.defaultStrings to your translations before initializing — same approach as any other locale.

Default strings

The plugin exposes this registry as $.fn.componentViewer.defaultStrings. By default it is the built-in English object used internally. You can:

• Replace the whole object with your locale (e.g. French, Spanish) so every key uses your text.
• Override specific keys by assigning a new object that includes all keys you need, or by copying the default and then changing only the keys you care about.

You do not pass strings via component options; there is no strings option. The only way to customize text is to set $.fn.componentViewer.defaultStrings before initializing the plugin (or before opening the overlay).

How to use it for your locale

Use only the keys listed in the Available keys table below. The registry has no duplicate keys: the same key is reused wherever that text appears (e.g. fullscreen for both overlay and video fullscreen button, pdf for PDF label and iframe title, audio for the audio type label). Do not use videoFullscreen, exitVideoFullscreen, typePdf, or typeAudio—those keys were removed; use fullscreen, exitFullscreen, pdf, and audio instead.

1. After loading the plugin script, set $.fn.componentViewer.defaultStrings to your translation object. Use the same keys as the built-in registry (see Available keys); any missing key falls back to the built-in English value.
2. Initialize the viewer as usual. All instances will use the strings from defaultStrings.

Example — French (keys from the current registry, no duplicates):

// Replace the entire registry with French
$.fn.componentViewer.defaultStrings = {
  close: 'Fermer',
  fullscreen: 'Plein écran',
  exitFullscreen: 'Quitter le plein écran',
  attachments: 'Pièces jointes',
  showAttachments: 'Afficher les pièces jointes',
  scrollCarouselLeft: 'Défiler le carrousel à gauche',
  scrollCarouselRight: 'Défiler le carrousel à droite',
  previousItem: 'Élément précédent',
  nextItem: 'Élément suivant',
  zoomOut: 'Zoom arrière',
  zoomLevel: 'Niveau de zoom',
  zoomIn: 'Zoom avant',
  switchToLightMode: 'Passer en mode clair',
  switchToDarkMode: 'Passer en mode sombre',
  playSlideshow: 'Lancer le diaporama',
  pauseSlideshow: 'Mettre en pause le diaporama',
  download: 'Télécharger',
  downloadSource: 'Télécharger la source',
  invalidImageUrl: 'URL d\'image invalide ou non sécurisée',
  imageLoadFailed: 'Impossible de charger l\'image',
  play: 'Lecture',
  pause: 'Pause',
  playbackSpeed: 'Vitesse de lecture',
  mute: 'Muet',
  unmute: 'Activer le son',
  thumbnails: 'Miniatures',
  previousPage: 'Page précédente',
  nextPage: 'Page suivante',
  rotate: 'Pivoter',
  print: 'Imprimer',
  pdf: 'PDF',
  previewNotAvailable: 'Aperçu non disponible pour ce fichier',
  file: 'Fichier',
  audio: 'Audio',
  couldNotLoadFileInline: 'Impossible de charger le fichier en ligne',
  noContentInline: 'Pas de contenu ou URL invalide pour la vue en ligne',
  noHtmlProvided: 'Aucun HTML fourni pour la vue HTML',
  typeVideo: 'Vidéo',
  typeCode: 'Code',
  typeHtml: 'HTML',
  typeError: '—'
};

$('#post').componentViewer({ /* options */ });

Example — override only a few keys (merge with default):

// Keep defaults and override only what you need
var defaults = $.fn.componentViewer.defaultStrings;
$.fn.componentViewer.defaultStrings = $.extend({}, defaults, {
  close: 'Cerrar',
  download: 'Descargar',
  fullscreen: 'Pantalla completa'
});
$('#post').componentViewer({});

Available keys

The registry uses the following keys. Your translation object should use these same keys; any key you omit falls back to the built-in English value. The registry has no duplicate keys—the same key is reused wherever that text appears (e.g. fullscreen for both overlay and video fullscreen button).

When to set defaultStrings

Set defaultStrings before you call .componentViewer(...) on any element. The plugin reads from it when building the overlay and when rendering labels (e.g. on open, theme toggle, fullscreen toggle). If you change defaultStrings after some viewers are already created, new opens and updated UI will use the new values; already-rendered text in the overlay may not update until the overlay is closed and reopened.

Callbacks (lifecycle)

All callbacks and their option names, types, and defaults are listed in Data and callbacks. Below is a quick reference and the order in which they run.

onRender return value

If onRender returns an object, it can include:

• toolbar — Array of toolbar item configs (or 'separator'). When provided, this replaces the built-in toolbar for this item; the plugin does not add the default Download or zoom widget. Use this when you render custom content and want full control over the footer.
• destroy — Optional function() called when the item is unloaded (e.g. on next/prev or close). Use it to tear down custom players, timers, or listeners.

If onRender appends to $stage but does not return an object with toolbar, the plugin still builds the toolbar from the renderer and toolbarItems. For the full option table, see Data and callbacks.

Execution order

When opening or loading an item, lifecycle callbacks run in this order:

1. onLoading(item, viewer) — before the stage is cleared and content is rendered
2. Content is rendered (built-in or onRender), toolbar resolved (onToolbar if present)
3. onOpen(item, $stage, viewer) — after the item is in the stage and toolbar is built
4. onComplete(item, viewer) — right after content is displayed; if a transition is used (e.g. next/prev with transition), this runs after the transition ends (~320ms)

When closing the overlay:

1. onCleanup(item, viewer) — at the start of the close process, before the close animation and teardown
2. Close animation and teardown (~300ms)
3. onClose(item, viewer) — after the overlay is closed and the instance is cleared

onThemeChange, onDownload, onRender, and onToolbar run when their respective actions occur and are not part of the open/close sequence above. For the complete list of callbacks and their option signatures, see Data and callbacks.

Public API

After initializing with $(container).componentViewer(options), call methods by name:

Static API

$.fn.componentViewer.getActive() — returns the currently open ComponentViewer instance, or null if the overlay is closed. Use it when you need the active viewer without a reference to the container (e.g. from a global button or callback). The returned instance supports refresh(), showLoader(), hideLoader(), showStripMessage(text, durationMs), close(), next(), prev(), goTo(index), currentItem(), items, idx, and opts.

var viewer = $.fn.componentViewer.getActive();
if (viewer) {
  viewer.showLoader();
  // ... do async work ...
  viewer.hideLoader();
  viewer.refresh();  // optional: reload current item
}

For cases where you don't have a container element (e.g. opening a chart or an iframe programmatically), use the static method:

$.componentViewer({
  items: [{ type: 'html', title: 'Preview', src: 'https://example.com' }],
  loop: false,
  showCounter: false
}).componentViewer('open', 0);

$.componentViewer(options) creates a temporary container internally, initializes the plugin with the given options, and returns the jQuery wrapper so you can chain .componentViewer('open', index) on it. This is equivalent to:

var $container = $('<div>');
$container.componentViewer(options);
$container.componentViewer('open', 0);

Combine with the items option (array of item objects) to open the viewer without any DOM elements. The items array replaces DOM-based item collection entirely.

Globals: $.fn.componentViewer.defaults (default options), $.fn.componentViewer.Icons (SVG strings for close, prev, next, zoom, download, etc.), $.fn.componentViewer.getActive() (returns the currently open viewer instance or null).

Accessibility

Set wcag: true to enable:

• Focus trap — Tab and Shift+Tab cycle only inside the overlay.
• Focus save/restore — Focus is saved when the overlay opens and restored when it closes.
• Initial focus — Focus moves to the close button when the overlay opens.
• ARIA — Overlay and shell get appropriate roles and attributes; buttons get aria-label where needed.

When wcag is false, these behaviors are disabled and no dialog ARIA is applied.

Responsiveness & gestures

The overlay is designed to work on desktop and on mobile devices (including in-app web views). The layout is responsive and touch-friendly; gestures are supported on touch devices without affecting desktop behavior.

Responsive UI

• Full-screen overlay — The overlay fills the viewport so it works on any screen size. Ensure your page uses a viewport meta tag (e.g. <meta name="viewport" content="width=device-width, initial-scale=1.0">) for correct scaling on mobile.
• Flexible layout — Header, stage, carousel, and footer adapt to available width and height. Buttons and controls are sized for touch when used on small screens.
• Body scroll lock — When the overlay is open, background page scroll is disabled so the overlay is the only scroll context and gestures are not lost to the page.

Desktop (mouse & keyboard)

• Navigation — Click prev/next arrows or use Left / Right arrow keys (when keyboardNav is true). No transition animation on click or keyboard.
• Images — Mouse wheel zooms in/out; drag to pan when zoomed. Zoom slider in the footer adjusts level.
• Close — Close button, backdrop click (if overlayClose), or Escape.

Mobile / touch / web view (gestures)

On touch devices, the following gestures are supported. They apply only to touch; desktop mouse behavior is unchanged.

Horizontal swipe is treated as navigation only when the gesture is clearly horizontal (threshold and direction); vertical swipe down is used for close. This avoids conflicts with pinch/pan on images. Single-finger horizontal swipe does not trigger image pan—only prev/next.

To disable touch navigation or swipe-to-close, set swipeNav: false or swipeToClose: false in the options.

Security

The plugin applies several measures to reduce XSS and related risks when rendering user or item data.

When you supply HTML via onRender or item.html (HTML type), you are responsible for ensuring that content is safe; the plugin does not sanitize arbitrary HTML content you inject.

Browser support

jQuery 1.7+ is required. jPlayer and PDF.js have their own browser requirements.

Comparison with Colorbox, Lightbox, and LC Lightbox

Colorbox is a popular jQuery lightbox for images and galleries. Lightbox (e.g. Lightbox2) is a classic image lightbox, often vanilla JS. LC Lightbox is a jQuery gallery popup plugin. Below is a side-by-side comparison to help you choose.

Side-by-side comparison

Examples

All examples below can be tried in index.html, which includes full demos for each feature. Use the API buttons at the bottom of that page to open specific cases programmatically.

Basic gallery

$('#gallery').componentViewer({
  toolbar: { download: true, zoom: true },
  pdf: { workerSrc: 'pdf.worker.min.js' }
});

Poll options (radio or checkbox)

Show a poll row above the toolbar for items that have pollOptionLabel. Use onSelect to handle the user's choice. For checkbox (multi-choice), set mode: 'checkbox'. Use pollOptionSelected: true in item data to show an option as already selected when the overlay opens.

$('#post').componentViewer({
  toolbar: { download: true, zoom: true },
  pollOption: {
    enabled: true,
    mode: 'radio',  // or 'checkbox'
    onSelect: function(item, selected, viewer) {
      console.log('Selected:', item.pollOptionLabel, selected);
    }
  },
  itemData: function($el, defaultItem) {
    defaultItem.pollOptionLabel = $el.data('poll-option-label');
    defaultItem.pollOptionId = $el.data('poll-option-id');
    if ($el.data('poll-option-selected')) defaultItem.pollOptionSelected = true;
    return defaultItem;
  }
});

See Case 13 in index.html (radio and checkbox demos).

Attachment comments (single or multiple)

Show a comment overlay on the media. Only item.comments (array) is supported: for one comment use [{ title?, author?, text }]; for multiple, the overlay shows prev/next arrows and a counter.

$('#post').componentViewer({
  showAttachmentComment: true,
  toolbar: { download: true, zoom: true },
  itemData: function($el, defaultItem) {
    // Single comment from data-* attributes
    var t = $el.data('title'), a = $el.data('author'), c = $el.data('comment');
    if (t || a || c) defaultItem.comments = [{ title: t || '', author: a || '', text: c || '' }];
    // Or multiple comments, e.g. from API:
    // if ($el.data('reviews')) defaultItem.comments = $el.data('reviews');
    return defaultItem;
  }
});

// Multiple comments per item
defaultItem.comments = [
  { title: 'Review 1', author: 'Alice', text: 'First comment...' },
  { title: 'Review 2', author: 'Bob', text: 'Second comment...' },
  { text: 'Anonymous note.' }
];

See Case 13b (single comment) and Case 13c (multiple comments) in index.html.

Image extract-text (OCR)

Show an "Extract text" button on image items. Set toolbar.extractText: true and provide the callbacks. The host performs OCR and passes the result to the plugin, which renders a word-level overlay on the image.

$('#gallery').componentViewer({
  toolbar: { download: true, zoom: true, extractText: true },
  canShowExtractText: function(item, viewer) {
    return (item.type || 'image') === 'image';
  },
  extractText: function(item, viewer, doneCallback, errorCallback) {
    // Call your OCR API; on success call doneCallback(resp), on failure call errorCallback(message)
    fetch('/api/getTextFromImage?src=' + encodeURIComponent(item.src))
      .then(function(r) { return r.json(); })
      .then(function(resp) {
        if (resp && resp.data) doneCallback(resp);
        else errorCallback('Could not extract text');
      })
      .catch(function() { errorCallback('Error when fetching text for the image'); });
  }
});

See Image extract-text for the full response shape and behavior details.

Image-only toolbar button

Add a custom toolbar button that appears only for image items, without changing the default toolbar for other types. Use the onToolbar callback: when item.type === 'image', append your button to a copy of the default toolbar and return it. The icon can be an SVG string or a CSS class name (e.g. for an icon font or background image); if it does not start with <, the plugin renders <i class="your-class"></i>.

$('#gallery').componentViewer({
  toolbar: { download: true, zoom: true },
  onToolbar: function (item, defaultToolbar, viewer) {
    if (item.type !== 'image') {
      return defaultToolbar;
    }
    var items = defaultToolbar.slice();
    if (items.length > 0) {
      items.push('separator');
    }
    items.push({
      id: 'my-image-action',
      icon: 'my-icon-class',   // CSS class — plugin renders <i class="my-icon-class"></i>
      label: 'My image action',
      showLabel: false,
      className: 'cv-tb-my-image-action',
      onClick: function (clickedItem, inst) {
        console.log('Image action', clickedItem.src);
      }
    });
    return items;
  }
});

Style the icon in your CSS, e.g. with an icon font or background-image:

.cv-overlay .cv-toolbar .cv-tb-my-image-action i.my-icon-class {
  font-size: 16px;
  /* or: background: url('icon.svg') no-repeat center; width: 16px; height: 16px; */
}

Carousel (thumbnail strip)

Enable a strip of thumbnails below the stage so users can jump to any item. The carousel toggle in the header shows or hides the strip. Set carousel.enabled: true; the strip appears when the container has more than one item.

$('#post').componentViewer({
  carousel: { enabled: true },
  toolbar: { download: true, zoom: true }
});

See Case 17 (carousel with multiple types) and Case 18 (few items, no scroll arrows) in index.html.

Slideshow

Auto-advance through items with a configurable interval (seconds). Use interval, not delay (there is no delay-in-milliseconds option). Combine with stageOnly for a minimal slideshow view.

$('#post').componentViewer({
  stageOnly: { enabled: true, hideNavigation: false },
  slideshow: { enabled: true, interval: 4 },
  toolbar: { download: true }
});

See Case 20 in index.html.

Video HD quality

Offer a high-quality stream via item.hdUrl or the video.onGetHdUrl callback. The HD button appears in the video toolbar; switching continues playback from the current time.

$('#post').componentViewer({
  video: {
    onGetHdUrl: function(item, viewer) {
      return item.attachmentId ? '/api/hd/' + item.attachmentId : null;
    }
  },
  itemData: function($el, defaultItem) {
    if (defaultItem.type === 'video' && $el.data('hd-url'))
      defaultItem.hdUrl = $el.data('hd-url');
    return defaultItem;
  }
});

See Case 11 (HD video) in index.html.

Video before play and HD button gate (jPlayer)

Gate unsupported or “processing” content before the first jPlayer init, and optionally hide the HD button when item.hdUrl exists but you do not want to offer HD yet.

$('#post').componentViewer({
  video: {
    canShowHDButton: function (item, viewer) {
      // Only when item.hdUrl is set; return false to hide HD despite hdUrl
      return item.allowHd !== false;
    },
    beforeVideoPlay: function (item, viewer, next, $stage) {
      var ext = (item.fileExt || '').toLowerCase();
      if (ext === 'mkv' || ext === 'avi') {
        next({
          gateContent: {
            html: '<div><p>This format may need transcoding. Playback might not work in all browsers.</p>' +
              '<p><button type="button" class="btn" data-cv-gate-proceed>Play anyway</button></p></div>',
            onProceed: function () {
              return { skippedTranscodeWarning: true };
            }
          }
        });
        return;
      }
      next();
    }
  }
});
// After the user proceeds through the gate, optional context:
// viewer._videoBeforePlayContext === { skippedTranscodeWarning: true }

Append directly on the overlay stage (no gateContent):

video: {
  beforeVideoPlay: function (item, viewer, next, $stage) {
    var $banner = $('<div class="my-video-notice"><p>Processing…</p>' +
      '<button type="button" class="btn-my-continue">Continue</button></div>');
    $stage.append($banner);
    $banner.find('.btn-my-continue').on('click', function () {
      $banner.remove();
      next();
    });
  }
}

Note: beforeVideoPlay and canShowHDButton are not used when jPlayer is missing and the native video fallback runs.

Loop disabled, counter hidden

$('#gallery').componentViewer({
  loop: false,
  showCounter: false,
  toolbar: { download: true, zoom: true }
});

See Case 15 (loop: false) and Case 16 (showCounter: false) in index.html.

Custom item data

$('#gallery').componentViewer({
  itemData: function($el, defaultItem) {
    defaultItem.canDelete = $el.data('can-delete');
    defaultItem.attachmentId = $el.data('id');
    return defaultItem;
  },
  toolbar: { download: true }
});

WCAG and custom download

$('#gallery').componentViewer({
  wcag: true,
  onDownload: function(item, viewer) {
    window.location = item.downloadUrl || item.src;
  }
});

Programmatic open

$('#gallery').componentViewer({ toolbar: { download: true } });
$('#gallery').componentViewer('open', 2);  // Open third item

Use the API buttons at the bottom of index.html to open any case by index.

Items array (no DOM elements)

Pass items directly via the items option — no .cv-item elements needed:

$('#container').componentViewer({
  items: [
    { type: 'image', title: 'Photo 1', src: '/images/photo1.jpg', downloadUrl: '/images/photo1.jpg' },
    { type: 'pdf',   title: 'Report',  src: '/docs/report.pdf' },
    { type: 'html',  title: 'Preview', src: 'https://example.com/embed' }
  ],
  loop: false,
  showCounter: true
});
$('#container').componentViewer('open', 0);

Static API (no container needed)

Use $.componentViewer(options) for one-off overlays without a persistent container:

// Open an iframe overlay for a Writer document
$.componentViewer({
  items: [{ type: 'html', title: 'My Document', src: '//writer.zoho.com/writer/zwpreview/abc123' }],
  loop: false,
  showCounter: false
}).componentViewer('open', 0);

// Open a chart using onRender
$.componentViewer({
  items: [{ type: 'custom', title: 'Engagement Graph' }],
  loop: false,
  showCounter: false,
  themeToggle: false,
  onRender: function(item, $stage, inst) {
    var $chart = $('<div id="myChart" style="width:100%;height:100%"></div>');
    $stage.append($chart);
    return {
      destroy: function() {
        var chart = $chart.data('chart');
        if (chart) { chart.destroy(); }
        $chart.remove();
      }
    };
  },
  onOpen: function(item, $stage, inst) {
    renderMyChart('myChart');
  }
}).componentViewer('open', 0);

HTML type with iframe (src)

For the html type, set item.src to a URL and the plugin creates a full-size iframe automatically. While the embed loads, an in-stage panel (cv-html-iframe-loader) shows the same cv-spinner as the overlay loader (same visual language as inline attachments that fetch src with cv-inline-loading). The panel is removed when the iframe fires load or error. The iframe has classes cv-html-iframe and cv-stage-iframe. While loading, the wrapper has cv-html-iframe-loading and the iframe is visually hidden.

$.componentViewer({
  items: [{
    type: 'html',
    title: 'Zoho Sheet',
    src: location.protocol + '//sheet.zoho.com/sheet/preview.do?rid=12345'
  }],
  loop: false,
  showCounter: false
}).componentViewer('open', 0);

When item.src is not set, the plugin falls back to item.html (raw HTML string, jQuery object, or DOM node).

Before open and gate content

Use beforeOpen(item, element, proceed) to run async logic (e.g. an access check) while the viewer is already open: the overlay appears right away with a circle loader and no footer toolbar until proceed runs. The callback is scheduled on the next tick after open, for both clicks and programmatic .componentViewer('open', index) / .componentViewer('open'). For items-only usage, element may be empty if item.$el is not set. Call proceed() or proceed({}) to load the item (options → viewer._openContext), or proceed({ gateContent: … }) to replace the loader with a gate screen in the stage (toolbar stays hidden until the real item loads). Gate HTML must include data-cv-gate-proceed; on click, onProceed() return value becomes _openContext and the item loads. Use resolveUrl to read viewer._openContext for signed URLs or audit flags.

Example: access check and audit gate — The user already sees the overlay with a loader while your API runs. If access is denied but an audit option is allowed, proceed({ gateContent: … }) shows the message and "Show preview"; when clicked, the item loads with a flag for your backend.

$('#gallery').componentViewer({
  beforeOpen: function(item, $el, proceed) {
    var fileId = item.$el.attr('data-file-id') || (item.src && item.src.match(/fileId=(\d+)/) && RegExp.$1);
    if (!fileId) {
      proceed();
      return;
    }
    $.get('/api/canAccessAttachment', { scopeID: scopeID, fileId: fileId })
      .done(function(data) {
        if (data.result === 'success') {
          proceed();
        } else if (data.canShowAuditPopup) {
          var auditHtml = '<div class="gate-message">' +
            '<p>If you preview this file, access will be recorded in audit logs.</p>' +
            '<button type="button" data-cv-gate-proceed>Show preview</button></div>';
          proceed({
            gateContent: {
              html: auditHtml,
              onProceed: function() {
                return { fromManageStorage: true };
              }
            }
          });
        } else {
          alert('You do not have access to this file.');
        }
      })
      .fail(function() {
        alert('Unable to check access.');
      });
  },
  resolveUrl: function(item, viewer, urlType) {
    var url = item.src || (urlType === 'zoomUrl' ? (item.zoomUrl || item.downloadUrl) : null) || '';
    if (viewer._openContext && viewer._openContext.fromManageStorage && url.indexOf('?') !== -1) {
      url += '&fromManageStorage=true';
    } else if (viewer._openContext && viewer._openContext.fromManageStorage) {
      url += (url ? '&' : '?') + 'fromManageStorage=true';
    }
    return url || null;
  }
});

In the example, the gate screen is built as a string; in practice you can clone a template (e.g. from your JSP) and ensure the continue button has data-cv-gate-proceed. The plugin injects the gate HTML into the stage, hides nav/counter, and binds the button. When the user clicks it, onProceed() runs, _openContext is set, and the real item loads; resolveUrl then appends fromManageStorage=true to URLs for that session.

Troubleshooting

Common issues and how to fix them.

Overlay doesn't open when I click an item

• Selector: Items must match the selector option (default .cv-item). Ensure each clickable element has that class (or your custom selector).
• Container: The plugin is bound to the container (e.g. $('#my-gallery').componentViewer(...)). Items must be inside that container.
• Event delegation: Clicks are bound to the container; ensure you're not calling preventDefault() or stopPropagation() on the same click.

PDF doesn't load or shows a blank page

• PDF.js: Include PDF.js and set pdf.workerSrc to the worker script path (e.g. pdf.worker.min.js). Without it, the plugin falls back to an iframe.
• CORS: If the PDF is on another origin, the server must send appropriate CORS headers; PDF.js fetches the file via XHR.
• URL: Use data-src or item.src for the PDF URL; data-type="pdf" and data-ext="PDF" help the plugin detect the type.

Video or audio doesn't play

• jPlayer: For full controls (play, pause, seek, volume), include jPlayer. Without it, the plugin uses native <video> / <audio>.
• Formats: Provide a URL the browser supports (e.g. MP4, WebM for video; MP3, OGG for audio). Use data-src or href and data-type="video" or data-type="audio".

Comment or poll doesn't show

• Comments: Set showAttachmentComment: true and provide item.comments as an array of { title?, author?, text } (e.g. via itemData or data-comments JSON).
• Poll: Set pollOption: { enabled: true } and give the item pollOptionLabel (and pollOptionId). Use itemData to map from data-poll-option-label etc.

Carousel or slideshow not working

• Carousel: Set carousel: { enabled: true }. The strip appears only when the container has more than one item.
• Slideshow: Set slideshow: { enabled: true, interval: 4 } (or other interval in seconds). Use with stageOnly for a minimal slideshow.