# Custom Highlights ## Content DsPdfViewer allows users to perform highlight operations with complete programmatic control. Highlighting is offered via the [IHighlightManager](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager) interface. Two primary types of highlights are provided: highlights for text and for custom shapes. There are also other operations for highlight retrieval and removal. ## Text Highlighting [highlightTextSegment](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#highlighttextsegment) method is provided for highlighting a specified segment of text on a given page. The appearance of the highlight can be customized using the optional parameters. highlightTextSegment method accepts the following parameters: | **Parameter** | **Description** | | --------- | ----------- | | pageIndex | The index of the page where the text segment is located (0-based). | | startCharIndex | The starting character index (0-based) of the text segment to highlight. | | endCharIndex | The ending character index (0-based) of the text segment to highlight. | | borderColor (optional) | The border color for the highlight in rgba, hex, or named color format. | | borderWidth (optional) | The width of the highlight border in pixels. | | clearPrevious (optional) | If true, clears existing highlights before adding the new one. | | color (optional) | The fill color for the highlight in rgba, hex, or named color format. | | skipPaint (optional) | If true, skips the immediate repaint of the text layer after adding the highlight. | Refer to the following example code to highlight a text segment on the first page of a document: ```javascript // Assume `viewer` is the instance of the DsPdfViewer control const highlightManager = viewer.highlightManager; await highlightManager.highlightTextSegment(0, 0, 12, { color: 'rgba(255, 255, 0, 0.5)', borderColor: 'orange', borderWidth: 1 }); ``` **Limitations** * The effectiveness of [highlightTextSegment](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#highlighttextsegment) is dependent on the presence and quality of a selectable text layer within the PDF document. ## Custom Shapes Highlighting DsPdfViewer provides the [addHighlight](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#addhighlight) method, which accepts pre-defined [ICustomHighlight](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/ICustomHighlight) objects, allowing users to place highlights at exact coordinates, independent of text layout. addHighlight method accepts the following parameters: | **Parameter** | **Description** | | --------- | ----------- | | pageIndex | The index of the page where the highlight should be added (0-based). | | highlight (ICustomHighlight) | The highlight object to be added. | | HighlightBehaviorArgs (optional) | Options for controlling the behavior when adding or clearing text highlights: | Refer to the following example code to add a custom rectangular highlight on the first page of a document: ```javascript const customHighlight = { rects: [{ x: 50, y: 100, w: 200, h: 25 }], color: 'rgba(0, 255, 0, 0.3)', borderColor: 'green', borderWidth: 2 }; const highlightIndex = highlightManager.addHighlight(0, customHighlight); ``` **Limitations** * The responsibility for calculating precise coordinates (rects) for [ICustomHighlight](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/ICustomHighlight) objects was placed on the user, which can be challenging without additional helper functions. ## Retrieving Highlights [getHighlightsForPage](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#gethighlightsforpage) method is provided to retrieve all highlights in a specific page. This method takes a pageIndex parameter and returns an array of ICusomtHighlight objects. Refer to the following example code to retrieve all highlights from the first page of a document: ```javascript const allHighlights = highlightManager.getHighlightsForPage(0); console.log(`Found ${allHighlights.length} highlights on page 0.`); ``` ## Removing Highlights DsPdfViewer provides [removeHighlight](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#removehighlight), [clearHighlightedSegments](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#clearhighlightedsegments), and [clearAllHighlights](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#clearallhighlights) methods for removing highlights on a PDF document. removeHighlight method removes a highlight at a specified index from the highlights on a given page. It takes a pageIndex parameter for the page, an index parameter for the index of the highlight to remove within the specified page, and an optional HighlightBehaviorArgs for optional behavior arguments like skipPaint. clearHighlightedSegments method clears all highlights from one or more specific pages. It takes a pageIndex parameter, which can either be an integer or an array of integers for multiple pages, and an optional HighlightBehaviorArgs parameter. clearAllHighlights method clears all highlights from all pages in the document. It takes an optional HighlightBehaviorArgs parameter. >type=note > **Note:** You can use [repaintTextLayer](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#repainttextlayer) method or [skipPaint](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/type-aliases/HighlightBehaviorArgs#skippaint) parameter to help with performance during mass updates, such as when using [clearHighlightedSegments](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#clearhighlightedsegments) or [clearAllHighlights](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#clearallhighlights) methods. Refer to the following example code to remove all highlights from the first and second page of a document: ```javascript highlightManager.clearHighlightedSegments([0, 1], { skipPaint: true }); // Usually the text layer is repainted after each bulk operation. Since skipPaint was set as true, visual updates are suppressed until repaintTextLayer method is called. highlightManager.repaintTextLayer([0, 1]); ``` **Limitations** * DsPdf does not include automatic saving of highlights back to the PDF file. The persistence lifecycle was designed to be managed by the host application. * ReplaceHighlight methods (e.g., [addReplaceHighlights](https://developer.mescius.com/document-solutions/javascript-pdf-viewer/api/interfaces/IHighlightManager#addreplacehighlights)) were implemented and documented specifically for the viewer's internal use (e.g., redaction features), making them complex and not recommended for general API consumers.