Configure PDF stamps with JavaScript

WebViewer supports three stamp types that you can apply to documents as annotations. All three appear in the Stamps panel, but each type defines a stamp's appearance differently and is managed separately, so changing one type's stamps doesn't affect the others.

The following table summarizes each type and its intended use.

Stamp type	Description	Preview
Preset	Use built-in PDF stamp designs, such as Approved, Draft, and Final. You can replace, append to, and organize these stamps into categories.
Document-backed	Use pages from PDF documents as reusable vector stamp appearances.
Custom	Generate stamps from configurable text, timestamps, colors, and font styles.

Get the Rubber Stamp tool

Use the AnnotationCreateRubberStamp tool to manage the stamps available in the UI.

JavaScript

WebViewer(
  {
    // WebViewer configuration
  },
  viewerElement
).then((instance) => {
  const { documentViewer } = instance.Core;

  const rubberStampTool = documentViewer.getTool(
    'AnnotationCreateRubberStamp'
  );
});

Preset stamps

WebViewer includes a set of built-in preset stamps, including the standard PDF stamps. Examples include:

• Approved
• AsIs
• Completed
• Confidential
• Departmental
• Draft
• Experimental
• Expired
• Final
• ForComment
• ForPublicRelease
• InformationOnly
• NotApproved
• NotForPublicRelease
• PreliminaryResults
• Sold
• TopSecret
• Void
• SHSignHere
• SHWitness
• SHInitialHere
• SHAccepted
• SBRejected

Call getDefaultStamps() to retrieve the complete list of built-in stamps.

JavaScript

const defaultStamps = rubberStampTool.getDefaultStamps();

console.log(defaultStamps);

Call getStandardStamps() to retrieve the preset stamps currently registered with the tool.

JavaScript

const currentStamps = rubberStampTool.getStandardStamps();

Replace preset stamps

Use registerPresetStamps() to replace the complete list of preset stamps displayed in the Stamps panel.

Each entry can be:

• The name of a built-in stamp
• An absolute image URL
• A base64 data URI
• An object containing an icon and optional category

JavaScript

rubberStampTool.registerPresetStamps({
  stamps: [
    'Approved',
    'Draft',
    'Final',
  ],
});

Calling registerPresetStamps() again replaces the previously registered list.

JavaScript

rubberStampTool.registerPresetStamps({
  stamps: [
    'Confidential',
    'TopSecret',
  ],
});

To remove all preset stamps from the panel, register an empty list:

JavaScript

rubberStampTool.registerPresetStamps({
  stamps: [],
});

Deprecation notice

setStandardStamps() is deprecated as of version 12.0. Use registerPresetStamps() when replacing the preset stamp list, or addPresetStamps() when appending stamps.

Add preset stamps

Use addPresetStamps() to append stamps to the current list.

JavaScript

rubberStampTool.addPresetStamps({
  stamps: [
    'Void',
    {
      icon: 'TopSecret',
      category: 'Sensitive',
    },
  ],
});

If registerPresetStamps() has not been called, addPresetStamps() appends entries to the built-in default stamps.

Both methods also accept an array directly:

JavaScript

rubberStampTool.addPresetStamps([
  'Approved',
  {
    icon: 'Draft',
    category: 'Review',
  },
]);

Use images as preset stamps

The icon property for stamps can be an absolute image URL or a base64 data URI.

JavaScript

rubberStampTool.addPresetStamps({
  stamps: [
    {
      icon: 'https://example.com/assets/company-seal.png',
      category: 'Company',
    },
  ],
});

When loading an image from another origin, ensure that the server permits cross-origin access.

An image-based preset stamp in a custom category.

Organize preset stamps into categories

Pass a category property with a preset stamp entry to control where it appears in the Stamps panel.

JavaScript

rubberStampTool.registerPresetStamps({
  stamps: [
    {
      icon: 'Approved',
      category: 'Review',
    },
    {
      icon: 'Draft',
      category: 'Review',
    },
    {
      icon: 'Confidential',
      category: 'Security',
    },
    'Void',
  ],
});

Preset stamps grouped by category.

A category can be an i18n translation key or a literal display string. Entries without a category appear in the default Standard Stamps category.

The configuration contains only serializable values, so you can store and restore it as JSON.

JavaScript

const presetStampConfig = {
  stamps: [
    {
      icon: 'Approved',
      category: 'Review',
    },
    'Draft',
  ],
};

localStorage.setItem(
  'presetStampConfig',
  JSON.stringify(presetStampConfig)
);

const savedConfig = JSON.parse(
  localStorage.getItem('presetStampConfig')
);

rubberStampTool.registerPresetStamps(savedConfig);

Document-backed stamps

Document-backed stamps use pages from a PDF document as stamp appearances. Each registered page becomes a selectable entry in the Stamps panel.

Unlike an image-based stamp, a document-backed stamp preserves the source page as a vector appearance when you place it.

Use setDocumentStamps() to register one or more PDF sources.

JavaScript

const result = await rubberStampTool.setDocumentStamps([
  {
    source: 'https://example.com/stamps/company-seal.pdf',
    title: 'Company Seal',
  },
]);

console.log(`Registered ${result.registeredCount} stamps`);

The source can be a URL or path string, a file, a blob, or an ArrayBuffer. Document-backed stamps will show under the Preset tab in the Stamps panel.

Each page of the source PDF appears as a separate stamp.

Register specific pages

By default, every page in each source document is registered as a separate stamp. Use pages to register specific pages. Page numbers are 1-indexed.

JavaScript

const result = await rubberStampTool.setDocumentStamps([
  {
    source: 'https://example.com/stamps/review-stamps.pdf',
    title: 'Review',
    pages: [1, 3],
  },
]);

The panel labels include the source title and page number. For example, Review 1 and Review 3.

Set defaults for all sources

The second argument to setDocumentStamps() provides defaults for all sources.

JavaScript

const result = await rubberStampTool.setDocumentStamps(
  [
    {
      source: 'https://example.com/stamps/review.pdf',
      title: 'Review',
    },
    {
      source: 'https://example.com/stamps/legal.pdf',
      title: 'Legal',
    },
  ],
  {
    pages: [1, 2],
    cropVisibleContent: true,
  }
);

A source-level value takes precedence over the corresponding global option.

JavaScript

const result = await rubberStampTool.setDocumentStamps(
  [
    {
      source: 'https://example.com/stamps/review.pdf',
      title: 'Review',
      pages: [3],
      cropVisibleContent: false,
    },
    {
      source: 'https://example.com/stamps/legal.pdf',
      title: 'Legal',
    },
  ],
  {
    pages: [1, 2],
    cropVisibleContent: true,
  }
);

In this previous example:

• Only page 3 of review.pdf is registered, without cropping.
• Pages 1 and 2 of legal.pdf are registered and cropped to their visible content.

Each source supports the following properties:

• source: Required PDF source. Accepts a URL string, File, Blob, or ArrayBuffer.
• title: Display title used in the Stamps panel.
• filename: Filename hint used while loading the source.
• extension: File extension override, such as pdf.
• pages: Page numbers to register. Registers all pages when omitted.
• cropVisibleContent: Whether to crop pages to their visible content. Defaults to true.
• category: Category in which the stamps appear.

Organize document-backed stamps into categories

Use the category property to group document-backed stamps in the panel.

JavaScript

await rubberStampTool.setDocumentStamps([
  {
    source: 'https://example.com/stamps/approval.pdf',
    title: 'Approval',
    category: 'Review',
  },
  {
    source: 'https://example.com/stamps/company-seal.pdf',
    title: 'Company Seal',
    pages: [1],
    category: 'Company',
  },
]);

If category is omitted, the stamps appear in the default Standard Stamps category.

Handle registration results

Registration failures are isolated. A failed source or page doesn't prevent other valid pages from being registered. The setDocumentStamps() method resolves with:

• registeredCount: Number of pages successfully registered as stamps.
• failures: Sources that could not be loaded or prepared.
• pageSuccesses: Pages that were successfully registered.
• pageFailures: Individual pages that could not be registered.

JavaScript

const {
  registeredCount,
  failures,
  pageSuccesses,
  pageFailures,
} = await rubberStampTool.setDocumentStamps([
  {
    source: 'https://example.com/stamps/review.pdf',
    title: 'Review',
    pages: [1, 2, 3],
  },
]);

console.log(`Registered ${registeredCount} stamps`);

failures.forEach(({ title, reason }) => {
  console.error(`Could not register ${title}`, reason);
});

pageFailures.forEach(({ title, pageNumber, reason }) => {
  console.error(
    `Could not register page ${pageNumber} of ${title}`,
    reason
  );
});

Replace document-backed stamps

Each call to setDocumentStamps() replaces the previously registered document-backed stamps.

It doesn't replace preset stamps or custom stamps.

JavaScript

await rubberStampTool.setDocumentStamps([
  {
    source: 'https://example.com/stamps/first-set.pdf',
  },
]);

// Replaces first-set.pdf with second-set.pdf.
await rubberStampTool.setDocumentStamps([
  {
    source: 'https://example.com/stamps/second-set.pdf',
  },
]);

Remove document-backed stamps

Use clearDocumentStamps() to remove all registered document-backed stamps and release their associated document resources.

JavaScript

rubberStampTool.clearDocumentStamps();

Preset stamps and custom stamps aren't affected.

Custom stamps

Custom stamps are generated from text and styling options. They can include:

• A title
• A subtitle or formatted timestamp
• Fill and text colors
• A font family
• Bold, italic, underline, or strikethrough styling
• A category

Use setCustomStamps() to replace the current custom stamp list.

JavaScript

WebViewer(
  {
    // WebViewer configuration
  },
  viewerElement
).then((instance) => {
  const { documentViewer, Annotations } = instance.Core;

  const rubberStampTool = documentViewer.getTool(
    'AnnotationCreateRubberStamp'
  );

  rubberStampTool.setCustomStamps([
    {
      title: 'Approved',
      subtitle: '[By $currentUser at] h:mm a, MMMM D, YYYY',
      color: new Annotations.Color('#4F9964'),
      category: 'Review',
    },
    {
      title: 'Reviewed',
      subtitle: '[By $currentUser on] MMMM Do, YYYY',
      color: new Annotations.Color('#2A85D0'),
      category: 'Review',
    },
  ]);
});

To render literal subtitle text instead of a formatted date, place the text in square brackets.

JavaScript

rubberStampTool.setCustomStamps([
  {
    title: 'Internal',
    subtitle: '[For internal use only]',
  },
]);

Users can also create custom stamps directly from the Custom stamps tab of the Stamps panel.

Stamps panel on the Custom tab showing an Internal custom stamp and the Add Stamp button.

Combine stamp types

You can register preset, custom, and document-backed stamps independently.

JavaScript

const { documentViewer, Annotations } = instance.Core;

const rubberStampTool = documentViewer.getTool(
  'AnnotationCreateRubberStamp'
);

// Replace the preset stamp list.
rubberStampTool.registerPresetStamps({
  stamps: [
    {
      icon: 'Approved',
      category: 'Review',
    },
    {
      icon: 'Confidential',
      category: 'Security',
    },
  ],
});

// Configure text-based custom stamps.
rubberStampTool.setCustomStamps([
  {
    title: 'Reviewed by legal',
    subtitle: '[By $currentUser on] MMMM D, YYYY',
    color: new Annotations.Color('#2A85D0'),
    category: 'Legal',
  },
]);

// Register PDF pages as vector document-backed stamps.
const result = await rubberStampTool.setDocumentStamps([
  {
    source: 'https://example.com/stamps/company-seals.pdf',
    title: 'Company Seal',
    pages: [1, 2],
    category: 'Company',
  },
]);

console.log(`Registered ${result.registeredCount} document-backed stamps`);