Customize annotation rendering

The PDF specification defines a standard set of annotations, but not how they appear on screen, as that is left to the document viewers. WebViewer lets you change how annotations are rendered when viewing them using the setCustomDrawHandler API. You can apply this to both standard and custom annotations in WebViewer.

If you're using custom annotations, they already have support for custom rendering. However, implementing one may be too much if you only want to change how annotations look, especially the standard set. This API will allow you to change how the annotations render without having to implement one.

Info: The setCustomDrawHandler and restoreDraw APIs are available in WebViewer 7.1+. The custom line and fill style APIs require WebViewer 12.2.0+.

Change annotation rendering

To change how annotations are rendered, you can use the setCustomDrawHandler API.

JavaScript

Annotations.setCustomDrawHandler(Annotations.RectangleAnnotation, function(ctx, pageMatrix, rotation, options) {
    options.originalDraw(ctx, pageMatrix, rotation);
    ctx.save();
    ctx.fillStyle = '#000000';
    ctx.fillText('Hello', this.X, this.Y + 12);
    ctx.restore();
});

Related links

• Annotations.setCustomDrawHandler

Rectangle annotation drawn with the custom draw handler

Alongside the annotation class you're targeting, you must provide a new custom draw function to the API to perform the rendering. It takes the regular parameters you would expect from an annotation draw function with an additional options parameter. If you are using an arrow function (bound function), then you can find the annotation through the options parameter.

JavaScript

// Draw handler signature
function(ctx, pageMatrix, rotation, options) {
  ...
}

Related links

• CustomAnnotationDrawHandler

Note that you get the annotation being drawn as well as the original annotation's draw function as part of the options parameter. This lets you reference the annotation and run the original draw function if needed.

Control appearances in other viewers

Although this works with annotations in WebViewer, other viewers will render annotations according to their own rendering. By default, setCustomDrawHandler will generate an appearance for the annotation so it will look similar in other viewers. If you want to turn this off, perhaps for changing rendering at certain times or if it's unnecessary, you can set the generateAppearance option in the third parameter of the API.

JavaScript

Annotations.setCustomDrawHandler(Annotations.RectangleAnnotation, function(ctx, pageMatrix, rotation, options) {
    ...
}, {
  generateAppearance: false,
  canvasMultiplier: 2, // Increase appearance quality at the cost of memory
});

Restore custom annotation rendering

When customizing annotation rendering, the original draw function is preserved. Calling the setCustomDrawHandler API again will not overwrite the original draw function. This lets you restore the annotation's original behavior with the restoreDraw API.

JavaScript

Annotations.restoreDraw(Annotations.RectangleAnnotation);

Related links

• Annotations.restoreDraw

Add custom line and fill styles

Info: The APIs in this section are available in WebViewer 12.2.0+.

In addition to custom annotation renderings, APIs allow customized line styling on existing line annotation tools and customized fill styling on existing shape annotation tools. These styles will appear in the style panel on the selected tools as icons (if available) or text if icons are omitted.

Any custom line styles will appear in the dropdowns under the style heading on line tools. Custom fill styles will appear under the fill section in a new dropdown under the style heading.

Custom fill and line styles in the style panel

Register line styles

To register custom line styles, you can use the registerCustomLineStyle API.

JavaScript

// Registers custom middle line styling that
// displays repeating Hs along the line
UI.registerCustomLineStyle({
  key: 'h-pattern-text',
  section: 'middle',
  appliesTo: ['all'],
  title: 'H Pattern (Text)',
  svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 24"><line x1="4" y1="12" x2="76" y2="12" stroke="currentColor" stroke-width="1.5"/><text x="16" y="14" font-size="8" text-anchor="middle" fill="currentColor">H</text><text x="32" y="14" font-size="8" text-anchor="middle" fill="currentColor">H</text><text x="48" y="14" font-size="8" text-anchor="middle" fill="currentColor">H</text><text x="64" y="14" font-size="8" text-anchor="middle" fill="currentColor">H</text></svg>',
  drawHandler: (ctx, pageMatrix, rotation, { annotation, originalDraw }) => {
    originalDraw(ctx, pageMatrix);

    const path = annotation.getPath?.();
    const segments = path?.length >= 2
      ? path.slice(1).map((endPt, index) => ({
        startPt: path[index],
        endPt,
      }))
      : [{
        startPt: annotation.getStartPoint?.() ?? annotation.Start,
        endPt: annotation.getEndPoint?.() ?? annotation.End,
      }].filter(({ startPt, endPt }) => startPt && endPt);

    const spacing = 18;
    const fontSize = Math.max(10, (annotation.StrokeThickness ?? 1) * 4);
    const color = annotation.StrokeColor?.toHexString?.() ?? '#000000';

    ctx.save();
    try {
      ctx.globalAlpha = annotation.Opacity ?? 1;
      ctx.fillStyle = color;
      ctx.font = `${fontSize}px Arial`;
      ctx.textAlign = 'center';
      ctx.textBaseline = 'middle';

      segments.forEach(({ startPt, endPt }) => {
        const dx = endPt.x - startPt.x;
        const dy = endPt.y - startPt.y;
        const length = Math.hypot(dx, dy);

        if (!length) {
          return;
        }

        const unitX = dx / length;
        const unitY = dy / length;

        for (let distance = 0; distance <= length; distance += spacing) {
          ctx.fillText(
            'H',
            startPt.x + unitX * distance,
            startPt.y + unitY * distance,
          );
        }
      });
    } finally {
      ctx.restore();
    }
  },
});

Line annotations with the H pattern line style

This API takes in a key that is tied to the custom line style and a custom draw handler responsible for drawing the custom line styling.

JavaScript

// Custom line style draw handler signature
function (ctx, pageMatrix, rotation, { annotation, originalDraw }) {
...
}

Alongside these two required parameters, the API also takes options to set which sections of the line the style applies to (section), which line tools this style can appear on (appliesTo), the title that will be shown in the style dropdown (title), an SVG string to display in the dropdown (svg), and extra bounds padding (padding). Re-registering a new custom style with a previously used and active key will override the key's previously associated handler and options and replace them with the new draw handler and options.

JavaScript

// Registers an end diamond line style that only applies to line annotations
UI.registerCustomLineStyle({
  key: 'custom-end-diamond',
  section: 'end',
  title: 'Diamond End',
  appliesTo: ['line'],
  svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 20"><path d="M32 10 L23 3 L14 10 L23 17 Z" fill="currentColor"/></svg>',
  padding: (annotation) =>
    Math.max(12, (annotation.StrokeThickness ?? 1) * 7),
  drawHandler: (
    ctx,
    pageMatrix,
    rotation,
    { annotation, originalDraw, activeSections },
  ) => {
    if (!activeSections.includes('middle')) {
      originalDraw(ctx, pageMatrix);
    }

    const startPt =
      annotation.getStartPoint?.() ?? annotation.Start;
    const endPt =
      annotation.getEndPoint?.() ?? annotation.End;

    if (!startPt || !endPt) {
      return;
    }

    const angle = Math.atan2(
      endPt.y - startPt.y,
      endPt.x - startPt.x,
    );
    const thickness = annotation.StrokeThickness ?? 1;
    const size = Math.max(8, thickness * 5);

    ctx.save();
    try {
      ctx.globalAlpha = annotation.Opacity ?? 1;
      ctx.strokeStyle =
        annotation.StrokeColor?.toHexString?.() ?? '#000000';
      ctx.fillStyle = ctx.strokeStyle;
      ctx.lineWidth = Math.max(1.5, thickness);
      ctx.lineJoin = 'round';

      ctx.save();
      ctx.translate(endPt.x, endPt.y);
      ctx.rotate(angle);
      ctx.beginPath();
      ctx.moveTo(0, 0);
      ctx.lineTo(-size * 0.65, -size * 0.55);
      ctx.lineTo(-size * 1.3, 0);
      ctx.lineTo(-size * 0.65, size * 0.55);
      ctx.closePath();
      ctx.fill();
      ctx.restore();
    } finally {
      ctx.restore();
    }
  },
});

Line annotations with the diamond end style

Register fill styles

To register custom fill styles, you can use the registerCustomFillStyle API.

JavaScript

// Registers a dot fill style for all shape annotation tools
UI.registerCustomFillStyle({
  key: 'fill-dots',
  title: 'Dots',
  appliesTo: ['all'],
  svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="4" cy="4" r="2" fill="currentColor"/><circle cx="16" cy="16" r="2" fill="currentColor"/></svg>',
  drawHandler: (ctx, pageMatrix, rotation, { annotation, originalDrawWithoutFill }) => {
    originalDrawWithoutFill();
    ctx.save();
    ctx.fillStyle = annotation.FillColor.toString();
    const { X, Y, Width, Height } = annotation;
    for (let x = X + 4; x < X + Width; x += 12) {
      for (let y = Y + 4; y < Y + Height; y += 12) {
        ctx.beginPath();
        ctx.arc(x, y, 2, 0, 2 * Math.PI);
        ctx.fill();
      }
    }
    ctx.restore();
  },
});

Shape annotations with custom dotted fill style

This API takes a key tied to the custom fill style and a custom draw handler that draws the custom fill styling within the shape annotation.

JavaScript

// Signature for fill draw handler
function (ctx, pageMatrix, rotation, { annotation, originalDraw, originalDrawWithoutFill, clipToShape }) {
...
}

Alongside these two required parameters, the API also takes options to set which type of shape annotation tool the style applies to, the title that will be shown in the style dropdown, an SVG string that will be displayed in the dropdown, a flag to use a custom function for clipping the fill to shape, and the actual custom function to be used in place of the default fill clipping function. Re-registering a new custom style with a previously used and active key will override the key's previously associated handler and options and replace them with the new draw handler and options.

JavaScript

// Registers a custom cross fill hatch with blue and orange lines
UI.registerCustomFillStyle({
  key: 'crosshatch-fill',
  appliesTo: ['rectangle', 'ellipse', 'polygon'],
  title: 'Crosshatch Fill',
  svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 24"><path d="M-4 24L20 0M8 24L32 0M20 24L44 0M-4 0L20 24M8 0L32 24M20 0L44 24" stroke="currentColor" stroke-width="2"/></svg>',
  drawHandler: (ctx, pageMatrix, rotation, { annotation, originalDrawWithoutFill, clipToShape }) => {
    originalDrawWithoutFill();
    ctx.save();
    clipToShape();
    ctx.globalAlpha = annotation.Opacity ?? 1;
    ctx.lineWidth = Math.max(1, (annotation.StrokeThickness || 1) / 2);
    ctx.translate(annotation.X + annotation.Width / 2, annotation.Y + annotation.Height / 2);
    ctx.rotate((rotation * Math.PI) / 180);
    
    const extent = Math.hypot(annotation.Width, annotation.Height);
    const spacing = 10;
    [
      { angle: Math.PI / 4, color: '#2A6F97' },
      { angle: -Math.PI / 4, color: '#E76F51' },
    ].forEach(({ angle, color }) => {
      ctx.save();
      ctx.rotate(angle);
      ctx.strokeStyle = color;
      ctx.beginPath();
      for (let offset = -extent; offset <= extent; offset += spacing) {
        ctx.moveTo(offset, -extent);
        ctx.lineTo(offset, extent);
      }
      ctx.stroke();
      ctx.restore();
    });
    ctx.restore();
  },
});

Shape annotations with the crosshatch fill style

Remove custom styles

To unregister currently registered custom line and fill styles, you can use the unregisterCustomLineStyle and unregisterCustomFillStyle APIs, respectively, which will clear the registered custom styles and their associated draw handlers.

JavaScript

// Unregisters H Line Style
UI.unregisterCustomLineStyle('h-pattern-text');

// Unregisters Dot Fill Style
UI.unregisterCustomFillStyle('fill-dots');

Next steps

Check out how to customize the serialization/deserialization behavior of annotations to save your custom properties.