Circle Annotation in JavaScript (ES6) PDF Viewer

21 Oct 202617 minutes to read

Circle is a shape annotation used to highlight circular regions or draw emphasis bubbles.

Circle annotations overview

Add Circle Annotation

Add circle annotation via UI

Use the annotation toolbar to:

  • Click the Edit Annotation button in the PDF Viewer toolbar.
  • Open the Shape Annotation dropdown.
  • Choose Circle, then draw on the page.

When in pan mode, selecting a shape annotation switches the viewer to text select mode.

Shape toolbar

Enable circle mode

The PDF Viewer library allows drawing circle annotations programmatically after enabling circle mode via button clicks.

<button id="circleMode">Circle</button>
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.resourceUrl = "https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib";
pdfviewer.appendTo('#PdfViewer');

document.getElementById('circleMode')?.addEventListener('click', () => {
    pdfviewer.annotationModule.setAnnotationMode('Circle');
});
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.serviceUrl = 'https://document.syncfusion.com/web-services/pdf-viewer/api/pdfviewer/';
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.appendTo('#PdfViewer');

document.getElementById('circleMode')?.addEventListener('click', () => {
    pdfviewer.annotationModule.setAnnotationMode('Circle');
});

Exit circle mode

<button id="setNone">Normal Mode</button>
document.getElementById('setNone')?.addEventListener('click', () => {
    pdfviewer.annotationModule.setAnnotationMode('None');
});

Add a circle annotation programmatically

Add shape annotations programmatically using the addAnnotation() method.

<button id="addCircleAnnotation">Add Circle annotation programmatically</button>
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer, CircleSettings } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.resourceUrl = "https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib";
pdfviewer.appendTo('#PdfViewer');

document.getElementById('addCircleAnnotation')?.addEventListener('click', () => {
    pdfviewer.annotation.addAnnotation('Circle', {
        offset: { x: 200, y: 620 },
        pageNumber: 1,
        width: 90,
        height: 90
    } as CircleSettings);
});
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer, CircleSettings } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.serviceUrl = 'https://document.syncfusion.com/web-services/pdf-viewer/api/pdfviewer/';
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.appendTo('#PdfViewer');

document.getElementById('addCircleAnnotation')?.addEventListener('click', () => {
    pdfviewer.annotation.addAnnotation('Circle', {
        offset: { x: 200, y: 620 },
        pageNumber: 1,
        width: 90,
        height: 90
    } as CircleSettings);
});

Edit Circle Annotation

Edit circle annotation in UI

You can select, move, and resize Circle annotations directly in the viewer:

  • Select a Circle to show its handles.
  • Move: drag inside the shape to reposition it on the page.
  • Resize: drag the corner handles to adjust its diameter.
  • Delete or access more options from the context menu.

Editing the properties of the circle annotation

The fill color, stroke color, thickness, and opacity of circle shape annotations can be edited using the Edit Color, Edit Stroke Color, Edit Thickness, and Edit Opacity tools in the annotation toolbar.

Editing fill color

The fill color of the annotation can be edited using the color palette provided in the Edit Color tool.

Edit fill color for shapes

Editing stroke color

The stroke color of the annotation can be edited using the color palette provided in the Edit Stroke Color tool.

Edit stroke color for shapes

Editing thickness

The thickness of the border of the annotation can be edited using the range slider provided in the Edit Thickness tool.

Edit thickness for shapes

Editing opacity

The opacity of the annotation can be edited using the range slider provided in the Edit Opacity tool.

Edit opacity for shapes

Edit an existing circle annotation programmatically

Use editAnnotation on items from annotationCollection.

<button id="editCircleAnnotation">Edit Circle annotation programmatically</button>
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.resourceUrl = "https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib";
pdfviewer.appendTo('#PdfViewer');

document.getElementById('editCircleAnnotation')?.addEventListener('click', () => {
    for (let i = 0; i < pdfviewer.annotationCollection.length; i++) {
        if (pdfviewer.annotationCollection[i].subject === 'Circle') {
            pdfviewer.annotationCollection[i].strokeColor = '#0000FF';
            pdfviewer.annotationCollection[i].thickness = 2;
            pdfviewer.annotationCollection[i].fillColor = '#FFFF00';
            pdfviewer.annotationCollection[i].annotationSelectorSettings.resizerShape = 'Circle';
            pdfviewer.annotation.editAnnotation(pdfviewer.annotationCollection[i]);
        }
    }
});
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.serviceUrl = 'https://document.syncfusion.com/web-services/pdf-viewer/api/pdfviewer/';
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.appendTo('#PdfViewer');

document.getElementById('editCircleAnnotation')?.addEventListener('click', () => {
    for (let i = 0; i < pdfviewer.annotationCollection.length; i++) {
        if (pdfviewer.annotationCollection[i].subject === 'Circle') {
            pdfviewer.annotationCollection[i].strokeColor = '#0000FF';
            pdfviewer.annotationCollection[i].thickness = 2;
            pdfviewer.annotationCollection[i].fillColor = '#FFFF00';
            pdfviewer.annotationCollection[i].annotationSelectorSettings.resizerShape = 'Circle';
            pdfviewer.annotation.editAnnotation(pdfviewer.annotationCollection[i]);
        }
    }
});

Default circle settings during initialization

Set default circleSettings before creating the control.

import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.resourceUrl = "https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib";
pdfviewer.circleSettings = { fillColor: 'orange', opacity: 0.6, strokeColor: 'pink' };
pdfviewer.appendTo('#PdfViewer');
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer } from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

let pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.serviceUrl = 'https://document.syncfusion.com/web-services/pdf-viewer/api/pdfviewer/';
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.circleSettings = { fillColor: 'orange', opacity: 0.6, strokeColor: 'pink' };
pdfviewer.appendTo('#PdfViewer');

Supported Border Styles

In addition to the default Solid border, Circle annotations support the following additional border styles:

  • Cloud — scalloped cloud border.
  • Dashed — dashed line border.

Use BorderStyle values such as BorderStyle.Cloud and BorderStyle.Dashed together with the optional borderDashArray and cloudIntensity settings in the circleSettings property.

Property Type Description
borderStyle BorderStyle Specifies the border style. Supported values: BorderStyle.Solid, BorderStyle.Cloud, and BorderStyle.Dashed.
borderDashArray number[] Specifies the dash pattern when borderStyle is BorderStyle.Dashed.
cloudIntensity number Specifies the cloud border intensity. Supported range: 1 to 2; default value: 1.

borderStyle, borderDashArray, and cloudIntensity are preserved during save, reload, import, and export.

Apply a Cloud Border

export enum BorderStyle {
    Solid = 'Solid',
    Dashed = 'Dashed',
    Cloud = 'Cloud'
}
var pdfviewer = new ej.pdfviewer.PdfViewer();
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.resourceUrl = "https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib";
pdfviewer.circleSettings = {
    fillColor: '#ffa500',
    strokeColor: '#ff6a00',
    thickness: 2,
    opacity: 0.9,
    borderStyle: ej.pdfviewer.BorderStyle.Cloud,
    cloudIntensity: 2
  };
pdfviewer.appendTo("#PdfViewer");

Apply a Dashed Border

var pdfviewer = new ej.pdfviewer.PdfViewer();
pdfviewer.documentPath = "https://cdn.syncfusion.com/content/pdf/pdf-succinctly.pdf";
pdfviewer.resourceUrl = "https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib";
pdfviewer.circleSettings = {
    fillColor: '#ffa500',
    strokeColor: '#ff6a00',
    thickness: 2,
    opacity: 0.9,
    borderStyle: ej.pdfviewer.BorderStyle.Dashed,
    borderDashArray: [5, 5]
  };
pdfviewer.appendTo("#PdfViewer");

Set properties while adding Individual Annotation

Set properties for individual annotations before creating the control using CircleSettings

After editing default color and opacity using the Edit Color and Edit Opacity tools, the values update to the selected settings.

Refer to the following code snippet to set the default Circle settings.

<button id="Circle">Add Circle</button>
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, CircleSettings} from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

const pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.documentPath = 'https://cdn.syncfusion.com/content/pdf/form-designer.pdf';
pdfviewer.resourceUrl = 'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib';
pdfviewer.appendTo('#PdfViewer');
//Apply Circle Settings while adding individual Annotation
document.getElementById('Circle')?.addEventListener('click', function () {
    pdfviewer.annotation.addAnnotation('Circle', {
        offset: { x: 200, y: 480 },
        pageNumber: 1,
        width: 150,
        height: 75,
        opacity: 0.5,
        strokeColor: '#FF0000',
        fillColor: '#000FFF',
        author: 'User1'
    } as CircleSettings);
});
import { PdfViewer, Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, CircleSettings} from '@syncfusion/ej2-pdfviewer';

PdfViewer.Inject(Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, ThumbnailView, BookmarkView, TextSelection, TextSearch, FormFields, FormDesigner, PageOrganizer);

const pdfviewer: PdfViewer = new PdfViewer();
pdfviewer.documentPath = 'https://cdn.syncfusion.com/content/pdf/form-designer.pdf';
pdfviewer.serviceUrl = 'https://document.syncfusion.com/web-services/pdf-viewer/api/pdfviewer/';
pdfviewer.appendTo('#PdfViewer');
//Apply Circle Settings while adding individual Annotation
document.getElementById('Circle')?.addEventListener('click', function () {
    pdfviewer.annotation.addAnnotation('Circle', {
        offset: { x: 200, y: 480 },
        pageNumber: 1,
        width: 150,
        height: 75,
        opacity: 0.5,
        strokeColor: '#FF0000',
        fillColor: '#000FFF',
        author: 'User1'
    } as CircleSettings);
});

View Sample on GitHub

See also