Stamps

Foxit PDF SDK for Web supports creating and managing stamp annotations through the full UI (UIExtension) and through APIs for stamp icon resources and adding stamp annotations to pages. The full UI includes stamp dropdowns, dynamic stamp entry points, and stamp management screens. Use the APIs in this topic when you need custom stamp resources, programmatic stamps, or integration with a business stamp library.

Related APIs include:

• PDFViewer.initAnnotationIcons(): Initialize a set of stamp icons; replaces the UIExtension default stamp list when set.
• PDFViewer.addAnnotationIcon(): Append a custom stamp icon to the stamp list.
• PDFViewer.removeAnnotationIcon(): Remove a custom stamp icon.
• PDFUI.getAnnotationIcons(): Read the stamp list; optionally return only custom stamps.
• PDFViewer.setFormatOfDynamicStamp() / getFormatOfDynamicStamp(): Set or read user and time format for default dynamic stamps.
• PDFPage.addAnnot(): Add a stamp annotation to a page.

To create dynamic stamps with user name, date/time, or custom fields, see Customize dynamic stamps.

Stamp types

UIExtension default stamps usually fall into three categories:

• Static: Fixed-appearance stamps such as Approved, Draft, Final, and similar.
• SignHere: Signing indicator stamps such as Sign Here, Initial, Witness, and similar.
• Dynamic: Stamps that include dynamic information such as user name and date or time.

The default stamp list comes from built-in SDK resources and should not be modified directly. Use the custom stamp APIs to add or replace stamps for your business.

Initialize a custom stamp list

PDFViewer.initAnnotationIcons(icons) initializes the stamp icon list. The API accepts an array; setting it replaces the default stamp list.

const pdfViewer = await pdfui.getPDFViewer();

await pdfViewer.initAnnotationIcons([
    {
        annotType: 'stamp',
        category: 'Business',
        name: 'Approved',
        fileType: 'png',
        url: 'https://example.com/stamps/approved.png',
        width: 150,
        height: 45
    },
    {
        annotType: 'stamp',
        category: 'Business',
        name: 'Rejected',
        fileType: 'pdf',
        url: 'https://example.com/stamps/rejected.pdf',
        width: 150,
        height: 45
    }
]);

NOTE

url supports HTTP URLs, Blob URLs, and Base64 URLs. The legacy object format ({ stamp: { category: { name: ... } } }) remains for compatibility; new integrations should use the array format.

Add a single stamp icon

PDFViewer.addAnnotationIcon(icon) appends one custom stamp to the stamp list.

await pdfViewer.addAnnotationIcon({
    annotType: 'stamp',
    category: 'Business',
    name: 'Reviewed',
    fileType: 'webp',
    url: 'https://example.com/stamps/reviewed.webp',
    width: 150,
    height: 45
});

Common fields:

Field	Description
annotType	Currently only 'stamp' is supported.
category	Stamp category name.
name	Stamp name; should be unique within a category.
fileType	Resource type: png, jpg, jpeg, bmp, webp, pdf, and others.
url	Stamp resource URL: HTTP, Blob URL, or Base64 URL.
width / height	Default stamp size in PDF coordinate units.

category and name should not contain special characters such as ~!@#$%^&*()=;[]{}.

Remove custom stamps

// Remove a specific stamp
await pdfViewer.removeAnnotationIcon('stamp', 'Business', 'Reviewed');

// Remove all stamps in a category
await pdfViewer.removeAnnotationIcon('stamp', 'Business', '');

// Remove all custom stamps
await pdfViewer.removeAnnotationIcon('stamp', '', '');

Read the stamp list

// Default and custom stamps
const allStamps = await pdfui.getAnnotationIcons('stamp', false);

// Custom stamps only
const customStamps = await pdfui.getAnnotationIcons('stamp', true);

Results are organized by category for use in a custom stamp picker.

Add a stamp to a page

If the stamp is already in the stamp list, specify appearance with icon and iconCategory.

const pdfViewer = await pdfui.getPDFViewer();
const pdfDoc = pdfViewer.getCurrentPDFDoc();
const page = await pdfDoc.getPageByIndex(0);

await page.addAnnot({
    type: 'stamp',
    rect: {
        left: 100,
        right: 250,
        top: 720,
        bottom: 675
    },
    icon: 'Approved',
    iconCategory: 'Business'
});

To add a stamp programmatically without showing it in the Viewer stamp list, pass iconInfo directly in the annotation JSON.

await page.addAnnot({
    type: 'stamp',
    rect: {
        left: 100,
        right: 250,
        top: 720,
        bottom: 675
    },
    iconInfo: {
        annotType: 'stamp',
        category: 'Business',
        name: 'Internal',
        fileType: 'png',
        url: 'https://example.com/stamps/internal.png',
        width: 150,
        height: 45
    }
});

Set default dynamic stamp format

Default dynamic stamps use dynamic information such as user name and time. Use PDFViewer.setFormatOfDynamicStamp(separator, timeFormat) to adjust the separator between user name and time and the time format.

await pdfViewer.setFormatOfDynamicStamp(' ', 'yyyy-mm-dd HH:MM:ss');

const format = await pdfViewer.getFormatOfDynamicStamp();
console.log(format);

Save stamps

Stamps are annotations. After adding, removing, or modifying stamps, export or save the PDF to persist changes.

const file = await pdfDoc.getFile({
    fileName: 'stamps.pdf'
});

Notes

• Stamp rectangles use PDF coordinates, not Viewer device pixels.
• initAnnotationIcons() replaces the default stamp list; use addAnnotationIcon() to append only.
• Before adding a stamp with icon / iconCategory, ensure the icon is initialized or added to the stamp list.
• Custom stamp resources must be reachable by the browser; configure CORS for cross-origin resources.
• Export or save the PDF after modifying stamp annotations to persist results.