Highlighter JS

The PDF Highlighter JS allows seamless integration using simple JavaScript. The script has no external dependencies.


The script is distributed with the Highlighter Server and can be referenced at /js/pdf-highlighter.min.js URI of your Highlighter installation.

To enable PDF highlighting, include and initialize the script:

<script src="/highlighter/js/pdf-highlighter.min.js"></script>
highlighterUrl: '/highlighter/',
documentLinkSelector: "a[href*='.pdf']",
querySelector: 'input[type=search]'

The Highlighter JS will attach to all PDF links in the web page and take the query for highlighting from the page element identified by the querySelector.

In the example above, we assume that proxying to Highlighter was setup at /highlighter path.


The script adds pdfHighlighter object to the page with the following methods available:

  • initPdfHighlighter – Initialization function accepting configuration object with options listed in the next section.
  • initOnDOMContentLoaded – As above except that initialization is performed after the document is loaded.

Configuration Object Options

The following configuration options are available:

  • highlighterUrl: string – PDF Highlighter service location.
  • documentLinkSelector: string – CSS selector for links that should be handled by PDF Highlighter. Defaults to: a[href*='.pdf'], a[href*='.PDF']
  • querySelector: string|function – CSS selector for a page element containing search query or a function that will return it. If the selector matches a text input element, its value will be used; otherwise, element text is used instead. If more than one element is found, the first matching element with text will be used. If not provided, the script will lookup for a "query" data attribute (see below).
  • updateHref: boolean – By default, the script attaches click handler to found PDF links. Set this option to true if you want it the script to update the element's href attribute instead.
  • viewer: object – If the viewer object is present in the config, the PDF document will always be opened in the viewer with highlighted hits loaded dynamically. The viewer object should contain url member with location of the Highlighting PDF Viewer to use and optionally viewer customization options.
  • checkStatus: boolean – When true, the script will check Highlighter's status endpoint to make sure it's running fine before attaching to PDF links.
  • apiKey: string – API key for the hosted PDF Highlighter.
  • resolveDocumentBase: boolean – When true (default), a relative document link will be resolved and sent to Highlighter as an absolute URL.
  • resolveXmlBase: boolean – The same as above but for highlights file location.
  • sendAbsoluteUrlsToHighlighter: boolean – This option is a shortcut for setting both resolveDocumentBase and resolveXmlBase.
  • updateAttr: string – Name of HTML element attribute to update with created highlighting request URL. Use of this option disables updateHref and PDF link click listener.
  • filterQuery: function(query) – Listener function used to filter query string before sending it to Highlighter.
  • onHighlightingLinkClick: function(element, context, event) – Link click listener. If it returns false, the click will be ignored.
  • updateHighlightingParams: function(data) – Listener function that can amend highlighting request parameters.
  • onHighlightingResult: function(result, element) – Listener for highlighting response JSON object. If it returns false, further processing (e.g. document open) will be prevented.
  • inlinePdfViewerAttr: object – If a PDF link has inlinePdfViewer class, it will be replaced with an inline PDF viewer added as an iframe. Any properties of this object will be added to the iframe as attributes.
  • overridePdfJS: boolean - If set to true, document links which are recognized as PDF.js viewer links will be overridden to open Highlighting PDF Viewer.

Supported Data Attributes

Data attributes generally correspond to the web service request parameters:

  • href - The script checks the element's href attribute first, but, if not set, it will check the data-href attribute as well. The value will be sent to the service as uri parameter.
  • xml - For compatibility with existing applications that use Adobe PDF highlight files, the plugin will first lookup for xml file reference in href fragment and query string. If not found, it will check the xml data attribute presence as well.
  • query
  • language
  • alt-url
  • view-url - PDF document location to use in Highlighting PDF viewer instead of href.
  • add-navigation
  • navigation
  • open-first-hl-page
  • remove-pages-without-matches
  • neighbour-pages

For detailed parameters description, see Highlighter API documentation.

Parameters common to multiple elements can be specified on a common parent. See them in action at https://api.highlight4.me/examples/