useStampAnnotationCreate

Returns a function that places an image on a page as a stamp annotation and resolves with its snapshot. To let users place an image by clicking the page instead, switch the interaction tool to { type: 'addImage', image } (see useSetInteractionMode).

const createStampAnnotation = useStampAnnotationCreate()

const stamp = await createStampAnnotation({ pageId, image, x, y, width?, height? })

The input is a UseAddStampAnnotationProps object:

The placement size:

• With both width and height, the image is stretched to exactly that size.
• With one of them, the other is completed from the image's aspect ratio.
• With neither, the image takes its natural size, one image pixel per user-space unit, scaled down to fit the page when larger.

Behavior

• The resolved value is a StampAnnotation snapshot (typed as Block): id, pageId, type: 'annotation', subtype: 'Stamp', the box x, y, width, and height (AnnotationGeometry), and imageId. The id is session-scoped: don't store it across page reloads.
• imageId (an ImageId string) identifies the placed picture. Stamps loaded from the document have imageId: null: they keep their saved appearance.
• The function is asynchronous because the target page may not be loaded yet and the image has to be stored first.
• An unknown pageId throws InvalidInputError; with no document loaded, the call throws DocumentNotLoadedError.

Example

import { stageImage, useStampAnnotationCreate } from '@sdk-pdf/react'

function useInsertLogo() {
  const createStampAnnotation = useStampAnnotationCreate()

  return async (pageId: string, file: File) => {
    const image = await stageImage(file)

    // A 120-point wide logo near the top-left corner of a US Letter page; the height
    // follows the aspect ratio.
    return createStampAnnotation({ pageId, image, x: 36, y: 700, width: 120 })
  }
}

To delete the stamp, see useBlockDelete.