A shape in Excel is usually there to point at something: the arrow on a diagram, the triangle that flags a number, the cloud that circles an area. Give it a hyperlink and the drawing becomes an entry point a reader can click. A shape, like a picture, is not a cell, and its hyperlink lives on the shape object itself, so both setting and reading one go through the worksheet's shape collection rather than its cell hyperlink collection. Spire.XLS for JavaScript does this in the browser on WebAssembly, handling input and output files through a virtual file system (VFS) with no backend service.

This article covers two core feature points:

• Set a hyperlink on a shape
• Read the hyperlink from a shape

For installation and project setup, see Integrating Spire.XLS for JavaScript in a React Project. The examples below assume Spire.XLS is installed and the WebAssembly module has been initialised.

Set a hyperlink on a shape

Setting a hyperlink on a shape is what turns a drawing into a clickable entry point: a reader who clicks the shape on the worksheet opens the address it points at. The link belongs to the shape itself rather than to a cell, so the shape has to be taken from the worksheet's shape collection first, and the address handed to its own link object. The steps are:

1. Load the font and the test data file into the VFS.
2. Load the workbook with workbook.LoadFromFile.
3. Add the shapes into the space left for them with sheet.PrstGeomShapes.AddPrstGeomShape.
4. Take the shape count from sheet.PrstGeomShapes.Count and walk every shape on the worksheet with it.
5. Take each shape's link object from its HyLink property and write the address into its Address.
6. Save the workbook with workbook.SaveToFile.
7. Dispose of the workbook with workbook.Dispose to free resources.

The complete code example below shows how to set a hyperlink on a shape in Excel in React:

function App() {
  const shapeHyperlink = async () => {
    // get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // check that the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'ShapeLink.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // load the workbook
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // take the first worksheet and add the three shapes into the space left for them
    const sheet = workbook.Worksheets.get(0);
    const shapes = sheet.PrstGeomShapes;
    shapes.AddPrstGeomShape(10, 1, 90, 60, xlsModule.PrstGeomShapeType.Triangle);
    shapes.AddPrstGeomShape(10, 3, 90, 60, xlsModule.PrstGeomShapeType.CurvedRightArrow);
    shapes.AddPrstGeomShape(10, 5, 90, 60, xlsModule.PrstGeomShapeType.Cloud);

    // set a hyperlink on each shape in turn
    const addresses = [
      'https://www.e-iceblue.com/Introduce/xls-for-javascript.html',
      'https://www.e-iceblue.com/Buy/Spire.XLS-JavaScript.html',
      'https://www.e-iceblue.com/Download/Spire-Office-JavaScript.html',
    ];
    for (let i = 0; i < shapes.Count; i++) {
      shapes.get(i).HyLink.Address = addresses[i];
    }

    // save the workbook
    const outputFileName = 'ShapeHyperlink.xlsx';
    workbook.SaveToFile({ fileName: outputFileName, fileFormat: xlsModule.FileFormat.Version2010 });

    // dispose of the workbook to free resources
    workbook.Dispose();

    // read the result file from the VFS and start the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add Hyperlinks to Shapes in Excel</h1>
      <button id="shape-hyperlink" onClick={shapeHyperlink}>Set a hyperlink on the shape</button>
    </div>
  );
}

export default App;

After running, the effect of setting a hyperlink on a shape:

Read the hyperlink from a shape

Reading the hyperlink off a shape is how a finished sheet is checked over: whether every shape carries a link, and whether they point at the right addresses. The addresses that come back are written out as a text file, which makes them easy to line up against a list of links. Shape hyperlinks are not kept in the cell hyperlink collection, so the shapes have to be taken from the worksheet one by one, and each one asked for its own link object. The steps are:

1. Load the font and the test data file into the VFS.
2. Load the workbook with workbook.LoadFromFile.
3. Take the shape count from sheet.PrstGeomShapes.Count and walk every shape on the worksheet with it.
4. Take this shape's link object from its HyLink property.
5. Read the target address from the link object's Address, collecting the addresses as you go.
6. Write the collected addresses into a text file with FS.writeFile, one address per line.
7. Dispose of the workbook with workbook.Dispose to free resources.

The complete code example below shows how to read the hyperlink from a shape in Excel in React:

function App() {
  const readShapeHyperlink = async () => {
    // get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // check that the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'ShapeHyperlinks.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // load the workbook
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // walk the shapes of the worksheet and read the hyperlink off each one
    const sheet = workbook.Worksheets.get(0);
    const shapes = sheet.PrstGeomShapes;
    const addresses = [];
    for (let i = 0; i < shapes.Count; i++) {
      addresses.push(shapes.get(i).HyLink.Address);
    }

    // write the addresses that were read into a text file
    const outputFileName = 'ReadShapeHyperlink.txt';
    window.dotnetRuntime.Module.FS.writeFile(outputFileName, addresses.join('\n'));

    // dispose of the workbook to free resources
    workbook.Dispose();

    // read the result file from the VFS and start the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/plain' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add Hyperlinks to Shapes in Excel</h1>
      <button id="read-shape-hyperlink" onClick={readShapeHyperlink}>Read the hyperlink from the shape</button>
    </div>
  );
}

export default App;

After running, the effect of reading the hyperlink from a shape:

FAQ

Why does a shape's hyperlink not show up in sheet.HyperLinks?

Cause: sheet.HyperLinks collects cell hyperlinks only. A shape is not a cell; it belongs to the worksheet's shape collection, and the link hangs on the shape object's HyLink.

Solution: Go through the shape collection. In this example, after a hyperlink was set on the shapes, sheet.HyperLinks.Count was still 0, and it was still 0 after the file was saved and opened again. Read a shape's link with sheet.PrstGeomShapes.get(i).HyLink.Address.

Get a Free License

Spire.XLS for JavaScript offers a 30-day full-featured free trial license with no functional limitations. Apply here to evaluate before purchasing.

Excel workbooks often need to tie scattered content together: one click on a summary page jumps to a detail worksheet, one click on a quote opens the source file kept beside it. That "jump elsewhere" ability belongs to cell hyperlinks, and the link type decides where the jump goes -- another worksheet inside the same workbook, or a file outside it. Spire.XLS for JavaScript does this in the browser through WebAssembly; input and output files are managed by a virtual file system (VFS), with no backend service required.

This article covers two feature points:

• Add a link to another worksheet
• Add a link to an external file

For installation and project setup, see Integrating Spire.XLS for JavaScript in a React Project. The examples below assume Spire.XLS is installed and the WebAssembly module has been initialized.

Add a link to another worksheet

A cross-sheet link solves the "jump from here to there" problem inside one workbook: it strings the content scattered across worksheets into a clickable path, so that the reader does not have to hunt for the right sheet. A link sits on a cell, so the first move is to create a hyperlink object on the target cell and then say, in turn, where it jumps and what text it shows. The steps are:

1. Load the font and the test data file into the VFS.
2. Load the workbook with workbook.LoadFromFile.
3. Create a hyperlink object on the target cell with sheet.HyperLinks.Add.
4. Mark the type as a workbook-internal link with the hyperlink's Type property, set to xlsModule.HyperLinkType.Workbook.
5. Set the text shown on the cell with the TextToDisplay property.
6. Write the jump target into the Address property, in the form "sheet name!cell", for example Data!B7.
7. Style the link text blue and underlined so that it reads differently from ordinary text.
8. Save the workbook with workbook.SaveToFile.
9. Dispose of the workbook with workbook.Dispose to free resources.

The complete code example below shows how to add a cross-sheet hyperlink to an Excel cell in React:

function App() {
  const linkToOtherSheet = async () => {
    // get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // check that the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'SheetLink.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // load the workbook
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // take the first worksheet and add a hyperlink object to cell B5
    const sheet = workbook.Worksheets.get(0);
    const cell = sheet.Range.get('B5');
    const hyperlink = sheet.HyperLinks.Add({ range: cell });

    // mark it as a workbook-internal link that points at cell B7 of the second worksheet
    hyperlink.Type = xlsModule.HyperLinkType.Workbook;
    hyperlink.TextToDisplay = 'View the full-year total in the data sheet';
    hyperlink.Address = 'Data!B7';

    // colour the link text blue and underline it so that it reads as a link
    cell.Style.Font.Color = xlsModule.Color.get_Blue();
    cell.Style.Font.Underline = xlsModule.FontUnderlineType.Single;

    // save the workbook
    const outputFileName = 'LinkToOtherSheetCell.xlsx';
    workbook.SaveToFile({ fileName: outputFileName, fileFormat: xlsModule.FileFormat.Version2010 });

    // dispose of the workbook to free resources
    workbook.Dispose();

    // read the result file from the VFS and start the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add Cross-Sheet and External File Links in Excel</h1>
      <button id="link-to-other-sheet" onClick={linkToOtherSheet}>Add a link to another worksheet</button>
      <button id="link-to-external-file" onClick={linkToExternalFile}>Add a link to an external file</button>
    </div>
  );
}

export default App;

After running, the effect of adding a cross-sheet link:

Add a link to an external file

A cross-sheet link can only jump within the same workbook, so once the target falls outside it, the link has to become a file link. It differs from a cross-sheet link in just two places: the type is marked as a file link, and the jump target becomes a file path -- either a full path or a path relative to the current workbook. The steps are:

1. Load the font and the test data file into the VFS.
2. Load the workbook with workbook.LoadFromFile.
3. Create a hyperlink object on the target cell with sheet.HyperLinks.Add.
4. Mark the type as a file link with the Type property, set to xlsModule.HyperLinkType.File.
5. Set the text shown on the cell with the TextToDisplay property.
6. Write the path of the external file into the Address property, for example ../files/Quote.xlsx.
7. Style the link text blue and underlined so that it reads differently from ordinary text.
8. Save the workbook with workbook.SaveToFile.
9. Dispose of the workbook with workbook.Dispose to free resources.

The complete code example below shows how to add an external-file hyperlink to an Excel cell in React:

function App() {
  const linkToExternalFile = async () => {
    // get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // check that the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'SheetLink.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // load the workbook
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });

    // take the first worksheet and add a hyperlink object to cell B6
    const sheet = workbook.Worksheets.get(0);
    const cell = sheet.Range.get('B6');
    const hyperlink = sheet.HyperLinks.Add({ range: cell });

    // mark it as a file link that points at a file outside the workbook
    hyperlink.Type = xlsModule.HyperLinkType.File;
    hyperlink.TextToDisplay = 'Open the external quote';
    hyperlink.Address = '../files/Quote.xlsx';

    // colour the link text blue and underline it so that it reads as a link
    cell.Style.Font.Color = xlsModule.Color.get_Blue();
    cell.Style.Font.Underline = xlsModule.FontUnderlineType.Single;

    // save the workbook
    const outputFileName = 'LinkToExternalFile.xlsx';
    workbook.SaveToFile({ fileName: outputFileName, fileFormat: xlsModule.FileFormat.Version2010 });

    // dispose of the workbook to free resources
    workbook.Dispose();

    // read the result file from the VFS and start the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add Cross-Sheet and External File Links in Excel</h1>
      <button id="link-to-other-sheet" onClick={linkToOtherSheet}>Add a link to another worksheet</button>
      <button id="link-to-external-file" onClick={linkToExternalFile}>Add a link to an external file</button>
    </div>
  );
}

export default App;

After running, the effect of adding an external-file link:

FAQ

Why does adding a link to a cell that already has text replace that text with the address

Reason: The text a cell shows is decided by TextToDisplay. Create a link without setting it and the address moves up to serve as the display text; the replacement happens the moment the link is added, so reading Range.Text afterwards returns the address rather than the original text.

Solution: Read the text before adding the link, then hand it back to TextToDisplay once the link is in place:

const cell = sheet.Range.get('B6');
const text = cell.Text;                  // keep the original text before adding the link
const hyperlink = sheet.HyperLinks.Add({ range: cell });
hyperlink.Type = xlsModule.HyperLinkType.File;
hyperlink.Address = '../files/Quote.xlsx';
hyperlink.TextToDisplay = text;          // hand the text back, so the cell still shows it

How do I remove a link but keep the text in the cell

Reason: The link and the text are two different things -- the link hangs on the cell, while the text is the cell's content. Range.ClearAll() clears the content, so using it to get rid of a link takes the text with it.

Solution: Remove the link by index with sheet.HyperLinks.RemoveAt, and the cell text stays as it was. For example, sheet.HyperLinks.RemoveAt(0) removes the first link; the text is still in the cell afterwards, it simply is no longer clickable.

Get a Free License

Spire.XLS for JavaScript offers a 30-day full-featured free trial license with no functional limitations. Apply here to evaluate before purchasing.

Page margins decide how much blank space sits between the body and the edge of the paper. Too little and the content crowds the edge and looks cramped; too much and a page holds very little. Existing PDFs usually have their layout fixed already — adding a ring of white space, or trimming the excess away, used to mean re-laying out page after page in desktop software; and once documents are processed in bulk by a program, the margins have to follow the layout.

This article shows how to increase or decrease PDF page margins with Spire.PDF for JavaScript. It is built on WebAssembly and loads, modifies and saves PDF documents directly in the browser, all locally, reading and writing files through a virtual file system (VFS) with no backend involved.

This article covers two core features:

• Increase PDF Page Margins
• Decrease PDF Page Margins

For installation and project setup, see How to Integrate Spire.PDF for JavaScript in a React Project. The examples below assume Spire.PDF is installed and the WebAssembly module is initialized.

Increase PDF Page Margins

Increasing the margins is like giving the document a larger sheet of paper: use CreateTemplate() to capture each page's content as a template and draw it onto a new page with a larger size, where PdfMargins reserves the blank space on all four sides — the content keeps its size, and a ring of white space appears around it.

function App() {
  const increasePdfMargins = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check whether the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // Load the PDF to be adjusted into the VFS
    const inputFileName = 'SampleDocument.pdf';
    await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}/data/`);

    // Load the original document and take its first page to compute the new page size
    const originalPdf = new pdfModule.PdfDocument();
    originalPdf.LoadFromFile(inputFileName);
    const firstPage = originalPdf.Pages.get_Item(0);

    // Add 40 points of padding on every side
    const marginsToAdd = new pdfModule.PdfMargins();
    marginsToAdd.Top = 40;
    marginsToAdd.Bottom = 40;
    marginsToAdd.Left = 40;
    marginsToAdd.Right = 40;

    // New page size = original size + the four margins, so the content area keeps its original size
    const newSize = new pdfModule.SizeF({
      width: firstPage.Size.Width + marginsToAdd.Left + marginsToAdd.Right,
      height: firstPage.Size.Height + marginsToAdd.Top + marginsToAdd.Bottom,
    });

    // Capture each page's content as a template and draw it onto a new page with margins
    const newPdf = new pdfModule.PdfDocument();
    for (let i = 0; i < originalPdf.Pages.Count; i++) {
      const template = originalPdf.Pages.get_Item(i).CreateTemplate();
      const page = newPdf.Pages.Add({ size: newSize, margins: marginsToAdd });
      page.Canvas.DrawTemplate({ template: template, location: new pdfModule.PointF(0, 0) });
    }

    const outputFileName = 'IncreaseMargins.pdf';
    newPdf.SaveToFile(outputFileName);
    newPdf.Close();
    originalPdf.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Increase PDF Page Margins</h1>
      <button onClick={increasePdfMargins}>
        Start
      </button>
    </div>
  );
}

export default App;

Each side is padded by 40 points, so the page grows and a ring of white space appears around the original content:

Decrease PDF Page Margins

Decreasing the margins is the reverse: the new page is smaller than the original, and the template is drawn shifted toward the top-left, trimming the excess white space on all four sides. Note that the amount trimmed per side must not exceed the blank space already present on that side of the original document, or the content will be cut off at the page boundary.

function App() {
  const decreasePdfMargins = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check whether the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // Load the PDF to be adjusted into the VFS
    const inputFileName = 'SampleDocument.pdf';
    await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}/data/`);

    // Load the original document and take its first page to compute the new page size
    const originalPdf = new pdfModule.PdfDocument();
    originalPdf.LoadFromFile(inputFileName);
    const firstPage = originalPdf.Pages.get_Item(0);

    // Trim 20 points of white space off every side; the value must not exceed the blank already on that side
    const trim = 20;

    // New page size = original size − the four trimmed values
    const newSize = new pdfModule.SizeF({
      width: firstPage.Size.Width - trim * 2,
      height: firstPage.Size.Height - trim * 2,
    });

    // The new page reserves no extra margins of its own
    const noMargins = new pdfModule.PdfMargins();
    noMargins.Top = 0;
    noMargins.Bottom = 0;
    noMargins.Left = 0;
    noMargins.Right = 0;

    // Capture each page as a template and draw it shifted toward the top-left, trimming the white space on all four sides
    const newPdf = new pdfModule.PdfDocument();
    for (let i = 0; i < originalPdf.Pages.Count; i++) {
      const template = originalPdf.Pages.get_Item(i).CreateTemplate();
      const page = newPdf.Pages.Add({ size: newSize, margins: noMargins });
      page.Canvas.DrawTemplate({ template: template, location: new pdfModule.PointF(-trim, -trim) });
    }

    const outputFileName = 'DecreaseMargins.pdf';
    newPdf.SaveToFile(outputFileName);
    newPdf.Close();
    originalPdf.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Decrease PDF Page Margins</h1>
      <button onClick={decreasePdfMargins}>
        Start
      </button>
    </div>
  );
}

export default App;

Each side is trimmed by 20 points of white space, so the page shrinks and the content moves closer to the paper's edge:

FAQ

Why not just change the page margins of the original document

Cause: Margins only decide where the content area begins, positioning content drawn afterward; content already drawn in the original document is fixed at absolute coordinates, and reassigning PageSettings.Margins does not move it.

Solution: Capture the original page's content as a template with CreateTemplate() and draw it onto a new page with margins — both examples above follow this approach.

The content gets cut off when decreasing the margins

Cause: The template is drawn starting at (-trim, -trim) while the page also shrinks by 2 × trim; once the amount trimmed exceeds the blank space already present on that side of the original document, the content crosses the page boundary and is clipped.

Solution: Set trim to no more than the blank space already present on that side. When the original document sits flush against the edge, widen it first with the increase approach, then consider narrowing it.

Why does the new page size have to include the margins

Cause: PdfMargins is the distance by which the canvas origin is inset; if the page size does not grow along with it, the content area ends up smaller than the original content and falls outside the page.

Solution: Compute the new page size as "original page size + the left and right (or top and bottom) margin sum" (when increasing), or "original page size − the left and right (or top and bottom) sum" (when decreasing), so the content area exactly fits the original content:

const newSize = new pdfModule.SizeF({
  width: firstPage.Size.Width + marginsToAdd.Left + marginsToAdd.Right,
  height: firstPage.Size.Height + marginsToAdd.Top + marginsToAdd.Bottom,
});

Get a Free License

If you want to remove the evaluation message from the result document, or lift the feature limitations, contact sales for a temporary license valid for 30 days.

Once a PDF reaches the review stage it becomes a file that gets passed back and forth: one page needs its key points marked, another needs a note on what to change, and the final copy needs an "Approved" stamp. Adding these marks by hand in a reader one at a time does not scale once there are many documents, and the next revision means doing it all over again. Build the marks into the generation flow and annotations come out together with the document.

Spire.PDF for JavaScript loads, modifies, and saves PDF documents in the browser with WebAssembly. Annotations are generated locally and files are read and written through a virtual file system (VFS), with no backend involved. This article uses PdfPage.Annotations to carry eight kinds of annotations: text markup, free text, popup, stamps, lines and polygons, plus web links, file links, and in-document jump links.

This article covers eight core features:

• Add a Text Markup Annotation
• Add a Free Text Annotation
• Add a Popup Annotation
• Add a Stamp Annotation
• Add a Shape Annotation
• Add a Web Link Annotation
• Add a File Link Annotation
• Add a Document Link Annotation

For installation and project setup, see How to Integrate Spire.PDF for JavaScript in a React Project. The examples below assume Spire.PDF is installed and the WebAssembly module is initialized.

Add a Text Markup Annotation

PdfTextMarkupAnnotation overlays a mark on existing text without changing the text itself. Set TextMarkupAnnotationType to Highlight and pick a color with TextMarkupColor to get the most common effect, a highlight that leaves the body text color untouched. The marked area is bounded by four corner points (QuadPoints) in absolute page coordinates, so clear the page margins first to make the canvas and the corner points line up. title and text are written into the annotation as its author and note; they are not drawn on the page and show up in the reader's comment panel.

function App() {
  const addTextMarkupAnnotation = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // The sample text on the page needs a font; load it into the VFS first
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    const doc = new pdfModule.PdfDocument();

    // Zero the page margins so the canvas coordinates line up with the annotation's corner points
    const margins = new pdfModule.PdfMargins();
    margins.Top = 0;
    margins.Bottom = 0;
    margins.Left = 0;
    margins.Right = 0;
    doc.PageSettings.Margins = margins;

    const page = doc.Pages.Add();

    const font = new pdfModule.PdfTrueTypeFont({
      fontFamily: 'Arial Unicode MS',
      size: 14,
      style: pdfModule.PdfFontStyle.Regular,
      unicode: true,
    });
    const brush = pdfModule.PdfBrushes.get_Black();

    const text = 'Highlight markup';

    // Draw the target text on the page first
    page.Canvas.DrawString({ s: text, font, brush, x: 80, y: 120 });

    // Measure the text so the markup covers it exactly
    const size = font.MeasureString({ text });
    const rect = new pdfModule.RectangleF({ x: 80, y: 120, width: size.Width, height: size.Height });

    const annotation = new pdfModule.PdfTextMarkupAnnotation({ title: 'Proofread', text: 'Needs review', rect, font });

    // Marked area: the four corner points of the text rectangle
    annotation.QuadPoints = [
      new pdfModule.PointF(rect.Left, rect.Top),
      new pdfModule.PointF(rect.Right, rect.Top),
      new pdfModule.PointF(rect.Left, rect.Bottom),
      new pdfModule.PointF(rect.Right, rect.Bottom),
    ];
    annotation.TextMarkupAnnotationType = pdfModule.PdfTextMarkupAnnotationType.Highlight;
    annotation.TextMarkupColor = new pdfModule.PdfRGBColor({ color: pdfModule.Color.get_LightSkyBlue() });

    page.Annotations.Add(annotation);

    const outputFileName = 'TextMarkupAnnotation.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add a Text Markup Annotation</h1>
      <button onClick={addTextMarkupAnnotation}>Add Annotation</button>
    </div>
  );
}

export default App;

A piece of text on the page covered by a highlight markup:

Add a Free Text Annotation

PdfFreeTextAnnotation draws a block of text directly on the page as a text box, which is common for notes, comments, or fill-in fields. The box position and size come from the rectangle passed to the constructor, and the font, border, background, and opacity can all be set afterward.

function App() {
  const addFreeTextAnnotation = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // The text box needs a font; load it into the VFS first
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    const doc = new pdfModule.PdfDocument();
    const page = doc.Pages.Add();

    const rect = new pdfModule.RectangleF({ x: 80, y: 120, width: 220, height: 60 });

    // The rectangle is passed to the constructor, so it decides the annotation's position and size
    const annotation = new pdfModule.PdfFreeTextAnnotation(rect);
    annotation.Text = 'This is a free text annotation';
    annotation.Font = new pdfModule.PdfTrueTypeFont({
      fontFamily: 'Arial Unicode MS',
      size: 14,
      style: pdfModule.PdfFontStyle.Regular,
      unicode: true,
    });
    annotation.Border = new pdfModule.PdfAnnotationBorder({ borderWidth: 1 });
    annotation.BorderColor = new pdfModule.PdfRGBColor({ color: pdfModule.Color.get_Gray() });
    annotation.Color = new pdfModule.PdfRGBColor({ color: pdfModule.Color.get_LightGoldenrodYellow() });
    annotation.Opacity = 0.8;

    page.Annotations.Add(annotation);

    const outputFileName = 'FreeTextAnnotation.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add a Free Text Annotation</h1>
      <button onClick={addFreeTextAnnotation}>Add Annotation</button>
    </div>
  );
}

export default App;

A block of free text with a border and a background on the page:

Add a Popup Annotation

PdfPopupAnnotation places an expandable popup window that leaves only an icon when collapsed, which suits a longer note that should not take up page space. The icon style is set with Icon, whose values include Note, Comment, Help, Insert, Key, NewParagraph, and Paragraph.

function App() {
  const addPopupAnnotation = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    const doc = new pdfModule.PdfDocument();
    const page = doc.Pages.Add();

    // A collapsed popup annotation is just an icon, so a zero-size rectangle marks its spot
    const rect = new pdfModule.RectangleF({ x: 120, y: 160, width: 0, height: 0 });

    const annotation = new pdfModule.PdfPopupAnnotation({ rectangle: rect, text: 'This is the popup annotation content' });
    annotation.Icon = pdfModule.PdfPopupIcon.Note;
    annotation.Open = true;
    annotation.Color = new pdfModule.PdfRGBColor({ color: pdfModule.Color.get_Yellow() });

    page.Annotations.Add(annotation);

    const outputFileName = 'PopupAnnotation.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add a Popup Annotation</h1>
      <button onClick={addPopupAnnotation}>Add Annotation</button>
    </div>
  );
}

export default App;

A popup annotation on the page, with its content expanded next to the icon:

Add a Stamp Annotation

PdfRubberStampAnnotation is used to place a stamp. It ships with a set of ready-made icons, so setting Icon produces a stamped frame with text and no need to draw the appearance yourself. The available icons include Approved, Confidential, Draft, Final, Expired, Sold, TopSecret, NotForPublicRelease, and a dozen or so more.

function App() {
  const addStampAnnotations = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    const doc = new pdfModule.PdfDocument();
    const page = doc.Pages.Add();

    // Place three common stamps with built-in icons
    const stamps = [
      { icon: pdfModule.PdfRubberStampAnnotationIcon.Approved, y: 200, color: pdfModule.Color.get_LightGreen() },
      { icon: pdfModule.PdfRubberStampAnnotationIcon.Confidential, y: 300, color: pdfModule.Color.get_LightPink() },
      { icon: pdfModule.PdfRubberStampAnnotationIcon.Draft, y: 400, color: pdfModule.Color.get_LightBlue() },
    ];

    for (const stamp of stamps) {
      const rect = new pdfModule.RectangleF({ x: 100, y: stamp.y, width: 150, height: 60 });

      const annotation = new pdfModule.PdfRubberStampAnnotation({ rectangle: rect, text: 'Stamp annotation' });
      annotation.Icon = stamp.icon;
      annotation.Color = new pdfModule.PdfRGBColor({ color: stamp.color });

      page.Annotations.Add(annotation);
    }

    const outputFileName = 'StampAnnotation.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add a Stamp Annotation</h1>
      <button onClick={addStampAnnotations}>Add Stamp</button>
    </div>
  );
}

export default App;

Three built-in icon stamps:

Add a Shape Annotation

Shape annotations attach geometric figures to the page as independent objects, unlike drawing directly on the canvas: they carry their own properties and notes, and readers can recognize and select them individually. The three classes cover lines, polygons, and polylines:

A polygon regenerates its appearance before it is added to the page, so set Author and Subject first; otherwise Add fails on a null reference.

function App() {
  const addShapeAnnotations = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    const doc = new pdfModule.PdfDocument();
    const page = doc.Pages.Add();

    // Line: given a start and an end point, with arrows at both ends
    const line = new pdfModule.PdfLineAnnotation({ linePoints: [80, 120, 300, 200], text: 'This is a line annotation' });
    line.lineBorder.BorderStyle = pdfModule.PdfLineBorderStyle.Solid;
    line.lineBorder.BorderWidth = 2;
    line.BeginLineStyle = pdfModule.PdfLineEndingStyle.Circle;
    line.EndLineStyle = pdfModule.PdfLineEndingStyle.ClosedArrow;
    line.BackColor = new pdfModule.PdfRGBColor({ color: pdfModule.Color.get_Blue() });
    page.Annotations.Add(line);

    // Polygon: vertices joined head to tail into a closed region
    const polygonPoints = [
      new pdfModule.PointF(80, 300),
      new pdfModule.PointF(160, 260),
      new pdfModule.PointF(240, 300),
      new pdfModule.PointF(200, 380),
      new pdfModule.PointF(120, 380),
      new pdfModule.PointF(80, 300),
    ];
    const polygon = new pdfModule.PdfPolygonAnnotation(page, polygonPoints);
    polygon.Color = new pdfModule.PdfRGBColor({ color: pdfModule.Color.get_PaleVioletRed() });
    polygon.Text = 'This is a polygon annotation';
    polygon.Author = 'E-ICEBLUE';
    polygon.Subject = 'polygon annotation demo';
    polygon.BorderEffect = pdfModule.PdfBorderEffect.BigCloud;
    polygon.ModifiedDate = new Date();
    page.Annotations.Add(polygon);

    // Polyline: vertices connected in order, not closed
    const polylinePoints = [
      new pdfModule.PointF(320, 300),
      new pdfModule.PointF(400, 260),
      new pdfModule.PointF(480, 340),
      new pdfModule.PointF(540, 300),
    ];
    const polyline = new pdfModule.PdfPolyLineAnnotation(page, polylinePoints);
    polyline.Color = new pdfModule.PdfRGBColor({ color: pdfModule.Color.get_Green() });
    polyline.Text = 'This is a polyline annotation';
    polyline.Border = new pdfModule.PdfAnnotationBorder({ borderWidth: 2 });
    page.Annotations.Add(polyline);

    const outputFileName = 'ShapeAnnotation.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add a Shape Annotation</h1>
      <button onClick={addShapeAnnotations}>Add Shape</button>
    </div>
  );
}

export default App;

Line, polygon, and polyline annotations on the same page:

Add a Web Link Annotation

PdfUriAnnotation turns a rectangular area into a link to a URL; when clicked, the reader hands it to the browser to open.

function App() {
  const addWebLinkAnnotation = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // The page needs a font; load it into the VFS first
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    const doc = new pdfModule.PdfDocument();
    const page = doc.Pages.Add();

    const font = new pdfModule.PdfTrueTypeFont({ fontFamily: 'Arial Unicode MS', size: 14, style: pdfModule.PdfFontStyle.Regular, unicode: true });
    const text = 'Visit the Spire.PDF product page';

    // A link area is invisible, so draw some text first as the clickable entry
    page.Canvas.DrawString({ s: text, font, brush: pdfModule.PdfBrushes.get_DodgerBlue(), x: 80, y: 120 });
    const size = font.MeasureString({ text });

    const rect = new pdfModule.RectangleF({ x: 80, y: 120, width: size.Width, height: size.Height });
    const link = new pdfModule.PdfUriAnnotation({ rectangle: rect });
    link.Uri = 'https://www.e-iceblue.com/Introduce/Spire-PDF-Javascript.html';

    page.Annotations.Add(link);

    const outputFileName = 'WebLinkAnnotation.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add a Web Link Annotation</h1>
      <button onClick={addWebLinkAnnotation}>Add Link</button>
    </div>
  );
}

export default App;

A web link annotation pointing to the product page, with the link area covering the text:

Add a File Link Annotation

PdfFileLinkAnnotation turns an area into a file link; when clicked, the reader opens the specified file through its system association.

function App() {
  const addFileLinkAnnotation = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // The page needs a font; load it into the VFS first
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    const doc = new pdfModule.PdfDocument();
    const page = doc.Pages.Add();

    const font = new pdfModule.PdfTrueTypeFont({ fontFamily: 'Arial Unicode MS', size: 14, style: pdfModule.PdfFontStyle.Regular, unicode: true });
    const text = 'Open Notepad';

    // Draw some text first as the clickable entry for the file link
    page.Canvas.DrawString({ s: text, font, brush: pdfModule.PdfBrushes.get_DodgerBlue(), x: 80, y: 120 });
    const size = font.MeasureString({ text });

    const rect = new pdfModule.RectangleF({ x: 80, y: 120, width: size.Width, height: size.Height });
    const link = new pdfModule.PdfFileLinkAnnotation(rect, 'C:\\Windows\\System32\\notepad.exe');

    page.Annotations.Add(link);

    const outputFileName = 'FileLinkAnnotation.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add a File Link Annotation</h1>
      <button onClick={addFileLinkAnnotation}>Add Link</button>
    </div>
  );
}

export default App;

A file link annotation that opens the specified file through its system association when clicked:

Add a Document Link Annotation

PdfDocumentLinkAnnotation handles in-document jumps: when clicked, it moves to the page and position given by a PdfDestination.

function App() {
  const addDocumentLinkAnnotation = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check that the module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // The page needs a font; load it into the VFS first
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    const doc = new pdfModule.PdfDocument();
    const page = doc.Pages.Add();

    // Append a second page as the jump target
    const target = doc.Pages.Add();

    const font = new pdfModule.PdfTrueTypeFont({ fontFamily: 'Arial Unicode MS', size: 14, style: pdfModule.PdfFontStyle.Regular, unicode: true });
    target.Canvas.DrawString({ s: 'This is the destination page', font, brush: pdfModule.PdfBrushes.get_Black(), x: 80, y: 120 });

    const text = 'Go to page 2';
    page.Canvas.DrawString({ s: text, font, brush: pdfModule.PdfBrushes.get_DodgerBlue(), x: 80, y: 120 });
    const size = font.MeasureString({ text });

    // Destination: 80 points down from the top of page 2, at 100% zoom
    const destination = new pdfModule.PdfDestination({ page: target });
    destination.Mode = pdfModule.PdfDestinationMode.Location;
    destination.Location = new pdfModule.PointF(0, 80);
    destination.Zoom = 1;

    const rect = new pdfModule.RectangleF({ x: 80, y: 120, width: size.Width, height: size.Height });
    const link = new pdfModule.PdfDocumentLinkAnnotation({ rectangle: rect, destination });

    page.Annotations.Add(link);

    const outputFileName = 'DocumentLinkAnnotation.pdf';
    doc.SaveToFile(outputFileName);
    doc.Close();

    // Read the generated file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add a Document Link Annotation</h1>
      <button onClick={addDocumentLinkAnnotation}>Add Link</button>
    </div>
  );
}

export default App;

A link on page 1 pointing to a position on page 2:

FAQ

Text on the page renders as boxes or blank

Cause: The body text and the annotation text both need a Unicode TrueType font. If the font is not loaded into the VFS, or PdfTrueTypeFont is used without unicode: true, the glyphs cannot be resolved and the saved file shows boxes or nothing at all.

Solution: Load the font file into /Library/Fonts/ in the VFS first, then reference the same font name with unicode enabled:

// Load the font into the VFS
await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

// Use the same font name and enable unicode
const font = new pdfModule.PdfTrueTypeFont({ fontFamily: 'Arial Unicode MS', size: 14, style: pdfModule.PdfFontStyle.Regular, unicode: true });

Link annotations leave no visible trace on the page

Cause: Link annotations only define a clickable area and an action; they draw no appearance of their own. Most readers do not draw a border around links, so the page looks unchanged after saving — which does not mean the annotation was not written.

Solution: To make it visible, draw text or a shape at the same rectangle and lay the link on top:

// Draw visible text first, then build the link from a rectangle of the same size
page.Canvas.DrawString({ s: text, font, brush: pdfModule.PdfBrushes.get_DodgerBlue(), x: 80, y: 120 });
const size = font.MeasureString({ text });
const rect = new pdfModule.RectangleF({ x: 80, y: 120, width: size.Width, height: size.Height });
const link = new pdfModule.PdfUriAnnotation({ rectangle: rect });
link.Uri = 'https://www.e-iceblue.com/';

The text markup annotation does not cover the text

Cause: The marked area is decided by QuadPoints, which uses absolute page coordinates and does not follow the text and align itself, while the canvas origin is pushed aside by the page margins. When the two are out of step, the mark lands beside the text or over empty space.

Solution: Zero the page margins first so the canvas and the corner points share one coordinate system, then measure the text with MeasureString and derive the four corner points from it:

const margins = new pdfModule.PdfMargins();
margins.Top = 0; margins.Bottom = 0; margins.Left = 0; margins.Right = 0;
doc.PageSettings.Margins = margins;

const size = font.MeasureString({ text: 'Highlight markup' });
const rect = new pdfModule.RectangleF({ x: 80, y: 120, width: size.Width, height: size.Height });
annotation.QuadPoints = [
  new pdfModule.PointF(rect.Left, rect.Top),
  new pdfModule.PointF(rect.Right, rect.Top),
  new pdfModule.PointF(rect.Left, rect.Bottom),
  new pdfModule.PointF(rect.Right, rect.Bottom),
];

Get a Free License

If you want to remove the evaluation message from the resulting documents, or to get rid of the functional limitations, please contact sales for a temporary license valid for 30 days.