Documents such as contract templates, onboarding registration forms and project initiation applications usually need a number of editable positions left in a fixed layout. A plain paragraph with an underline can produce a similar effect, but the person filling it in may delete the instructions by accident, and there is no way to restrict the type of content that can be entered. Word content controls are designed for exactly this purpose: they wrap a piece of content into a separate object with a type and properties, which both constrains the filling range and makes the content easy for programs to recognize and process in batches.

Inserting content controls one by one in desktop software is suitable for a small number of documents; once documents have to be generated in batches in a web workflow, manual operation becomes impractical. Uploading files to a server for processing, on the other hand, takes the documents off the user's device. This article uses Spire.Doc for JavaScript to add content controls directly in the browser: documents are read into memory through the virtual file system (VFS), written back to the VFS after processing and then downloaded. The whole process does not depend on Office and requires no backend service.

This article covers the following topics:

• Add a Text Content Control
• Add a Rich Text Content Control
• Add a Picture Content Control

All three control types are created by StructureDocumentTagInline; they differ in the value of SDTProperties.SDTType and in the control properties:

For installation and project setup, refer to Integrating Spire.Doc for JavaScript in a React Project. The examples below assume that Spire.Doc is installed and the WebAssembly module is initialized.

Add a Text Content Control

A text content control accepts plain text input and is suitable for fields that do not allow complex formatting, such as a project name, a contact person or a department name. Create an inline control with StructureDocumentTagInline, set SDTType to SdtType.Text, and then use SdtText to control whether multiple lines are allowed.

The following members are involved in adding a text content control:

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the font, create a document with the Document class and add a section.
3. Create a StructureDocumentTagInline control in the paragraph and set SDTType to SdtType.Text.
4. Set the multiline property with SdtText, and write TextRange content into SDTContent.
5. Save the result file with SaveToFile(), read it from the VFS and trigger a browser download.

The code for adding a text content control is as follows:

function App() {
  const addTextControl = async () => {
    // Get the Spire.Doc WASM module
    const wasmModule = window.wasmModule?.spiredoc;

    if (!wasmModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the font
    await window.spire.FetchFileToVFS('arial.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    await window.spire.FetchFileToVFS('arialbd.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    // Create a document and add a section
    const doc = new wasmModule.Document();
    const section = doc.AddSection();

    // Add the title paragraph
    const titleParagraph = section.AddParagraph();
    const titleRange = titleParagraph.AppendText('Project Initiation Application');
    titleRange.CharacterFormat.FontName = 'Arial';
    titleRange.CharacterFormat.FontSize = 19;
    titleRange.CharacterFormat.Bold = true;
    titleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 15, 110, 90);
    titleParagraph.Format.AfterSpacing = 6;

    // Add the subtitle
    const subtitleParagraph = section.AddParagraph();
    const subtitleRange = subtitleParagraph.AppendText('Technical Committee — November 2026');
    subtitleRange.CharacterFormat.FontName = 'Arial';
    subtitleRange.CharacterFormat.FontSize = 9;
    subtitleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);
    subtitleParagraph.Format.AfterSpacing = 16;

    // Add the text before the control
    const paragraph = section.AddParagraph();
    paragraph.AppendText('Project name:  ');

    // Create an inline content control and add it to the paragraph
    const sdt = new wasmModule.StructureDocumentTagInline(doc);
    paragraph.ChildObjects.Add(sdt);

    // Set the control type to text
    sdt.SDTProperties.SDTType = wasmModule.SdtType.Text;
    const textProperties = new wasmModule.SdtText(true);
    textProperties.IsMultiline = true;
    sdt.SDTProperties.ControlProperties = textProperties;

    // Set the alias, tag and appearance
    sdt.SDTProperties.Alias = 'Project Name';
    sdt.SDTProperties.Tag = 'project-name';
    sdt.SDTProperties.Appearance = wasmModule.SdtAppearance.Tags;

    // Write the content of the control
    const content = new wasmModule.TextRange(doc);
    content.Text = 'Intelligent Document Processing Platform (Phase II)';
    sdt.SDTContent.ChildObjects.Add(content);

    // Add a filling note
    const noteParagraph = section.AddParagraph();
    noteParagraph.Format.BeforeSpacing = 10;
    const noteRange = noteParagraph.AppendText('Note: keep the project name within 30 characters and consistent with the project approval document.');
    noteRange.CharacterFormat.FontName = 'Arial';
    noteRange.CharacterFormat.FontSize = 9;
    noteRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);

    // Save the result file
    const outputFileName = 'AddTextContentControl.docx';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });
    doc.Dispose();

    // 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/vnd.openxmlformats-officedocument.wordprocessingml.document' });
    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 Text Content Control</h1>
      <button onClick={addTextControl}>Generate Document</button>
    </div>
  );
}

export default App;

Document after adding a text content control:

Alias, Tag and Appearance of a Content Control

SDTProperties has three groups of properties that are unrelated to the content itself but closely related to later processing:

The example sets Appearance to SdtAppearance.Tags so that the generated document directly shows the control boundaries and aliases, which makes the result easy to check. If it is not set, Word uses the default display and the control looks no different from ordinary text.

Add a Rich Text Content Control

A rich text content control is also based on SdtText, but its type is SdtType.RichText. It allows fonts, font sizes, colors and bold formatting to be preserved inside the control, which makes it suitable for passages that need emphasis, such as version highlights, approval comments or supplementary contract clauses.

Compared with the text content control, the steps are basically the same, with one difference: SDTType uses SdtType.RichText, and the content of the control can be split into several TextRange objects that are formatted separately.

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the font, create a document with the Document class and add a section.
3. Create a StructureDocumentTagInline control in the paragraph and set SDTType to SdtType.RichText.
4. Create several TextRange objects in order, set their colors and bold settings, and add them to SDTContent.
5. Save the result file with SaveToFile(), read it from the VFS and trigger a browser download.

The code for adding a rich text content control is as follows:

function App() {
  const addRichTextControl = async () => {
    // Get the Spire.Doc WASM module
    const wasmModule = window.wasmModule?.spiredoc;

    if (!wasmModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the font
    await window.spire.FetchFileToVFS('arial.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    await window.spire.FetchFileToVFS('arialbd.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    // Create a document and add a section
    const doc = new wasmModule.Document();
    const section = doc.AddSection();

    // Add the title paragraph
    const titleParagraph = section.AddParagraph();
    const titleRange = titleParagraph.AppendText('Release Notes');
    titleRange.CharacterFormat.FontName = 'Arial';
    titleRange.CharacterFormat.FontSize = 19;
    titleRange.CharacterFormat.Bold = true;
    titleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 15, 110, 90);
    titleParagraph.Format.AfterSpacing = 6;

    // Add the subtitle
    const subtitleParagraph = section.AddParagraph();
    const subtitleRange = subtitleParagraph.AppendText('Northstar Document Platform — 2026.11');
    subtitleRange.CharacterFormat.FontName = 'Arial';
    subtitleRange.CharacterFormat.FontSize = 9;
    subtitleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);
    subtitleParagraph.Format.AfterSpacing = 16;

    // Add the text before the control
    const paragraph = section.AddParagraph();
    paragraph.AppendText('Release highlights:  ');

    // Create an inline content control and add it to the paragraph
    const sdt = new wasmModule.StructureDocumentTagInline(doc);
    paragraph.ChildObjects.Add(sdt);

    // Set the control type to rich text
    sdt.SDTProperties.SDTType = wasmModule.SdtType.RichText;
    const textProperties = new wasmModule.SdtText(true);
    textProperties.IsMultiline = true;
    sdt.SDTProperties.ControlProperties = textProperties;

    // Set the alias, tag and appearance
    sdt.SDTProperties.Alias = 'Release Highlights';
    sdt.SDTProperties.Tag = 'release-highlights';
    sdt.SDTProperties.Appearance = wasmModule.SdtAppearance.Tags;

    // First text fragment: green body text
    const firstRange = new wasmModule.TextRange(doc);
    firstRange.Text = 'This release supports';
    firstRange.CharacterFormat.FontName = 'Arial';
    firstRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 0, 128, 0);
    sdt.SDTContent.ChildObjects.Add(firstRange);

    // Second text fragment: orange bold keyword
    const secondRange = new wasmModule.TextRange(doc);
    secondRange.Text = 'content controls';
    secondRange.CharacterFormat.FontName = 'Arial';
    secondRange.CharacterFormat.Bold = true;
    secondRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 237, 125, 49);
    sdt.SDTContent.ChildObjects.Add(secondRange);

    // Third text fragment: green body text
    const thirdRange = new wasmModule.TextRange(doc);
    thirdRange.Text = ' for batch writing and format validation.';
    thirdRange.CharacterFormat.FontName = 'Arial';
    thirdRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 0, 128, 0);
    sdt.SDTContent.ChildObjects.Add(thirdRange);

    // Add a tip
    const noteParagraph = section.AddParagraph();
    noteParagraph.Format.BeforeSpacing = 10;
    const noteRange = noteParagraph.AppendText('Tip: the content inside a rich text control can be split into several TextRange objects, each with its own font, color and bold setting.');
    noteRange.CharacterFormat.FontName = 'Arial';
    noteRange.CharacterFormat.FontSize = 9;
    noteRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);

    // Save the result file
    const outputFileName = 'AddRichTextContentControl.docx';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });
    doc.Dispose();

    // 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/vnd.openxmlformats-officedocument.wordprocessingml.document' });
    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 Rich Text Content Control</h1>
      <button onClick={addRichTextControl}>Generate Document</button>
    </div>
  );
}

export default App;

Document after adding a rich text content control:

Combining Multiple Formats in a Rich Text Control

The content of a rich text control is made up of several TextRange objects joined in order. Each added TextRange appends a piece of text with its own formatting inside the control: it is possible to recolor only a keyword or to make a whole passage bold. Note that the CharacterFormat of a TextRange only affects that fragment and does not apply to the other content in the control; if the whole passage should share the same formatting, set it on each fragment.

Add a Picture Content Control

A picture content control holds a replaceable picture and is suitable for scenarios such as company logos, product diagrams and signature or seal positions. It is created in the same way as the previous two types: set SDTType to SdtType.Picture and use a DocPicture object as the control content.

A picture content control does not set its properties through ControlProperties; instead, the DocPicture is added directly to SDTContent. The example reads logo.png from public/data, so put that picture in the project's public/data directory before running it. Picture dimensions are measured in points and can be adjusted after LoadImage():

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the font and the sample picture into the VFS, then create a document and add a section.
3. Create a StructureDocumentTagInline control and set SDTType to SdtType.Picture.
4. Create a DocPicture, load the picture, set its width and height, and add it to SDTContent.
5. Save the result file with SaveToFile(), read it from the VFS and trigger a browser download.

The code for adding a picture content control is as follows:

function App() {
  const addPictureControl = async () => {
    // Get the Spire.Doc WASM module
    const wasmModule = window.wasmModule?.spiredoc;

    if (!wasmModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the font and the sample picture
    await window.spire.FetchFileToVFS('arial.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    await window.spire.FetchFileToVFS('arialbd.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    await window.spire.FetchFileToVFS('logo.png', '', `${process.env.PUBLIC_URL}/data/`);

    // Create a document and add a section
    const doc = new wasmModule.Document();
    const section = doc.AddSection();

    // Add the title paragraph
    const titleParagraph = section.AddParagraph();
    const titleRange = titleParagraph.AppendText('Brand Identity');
    titleRange.CharacterFormat.FontName = 'Arial';
    titleRange.CharacterFormat.FontSize = 19;
    titleRange.CharacterFormat.Bold = true;
    titleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 15, 110, 90);
    titleParagraph.Format.AfterSpacing = 6;

    // Add the subtitle
    const subtitleParagraph = section.AddParagraph();
    const subtitleRange = subtitleParagraph.AppendText('Use the following logo on all external documents');
    subtitleRange.CharacterFormat.FontName = 'Arial';
    subtitleRange.CharacterFormat.FontSize = 9;
    subtitleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);
    subtitleParagraph.Format.AfterSpacing = 16;

    // Add the text before the picture
    const label = section.AddParagraph();
    label.AppendText('Company logo: ');

    // Create an inline content control and add it to a new paragraph
    const paragraph = section.AddParagraph();
    const sdt = new wasmModule.StructureDocumentTagInline(doc);
    paragraph.ChildObjects.Add(sdt);

    // Set the control type to picture
    sdt.SDTProperties.SDTType = wasmModule.SdtType.Picture;
    sdt.SDTProperties.Alias = 'Company Logo';
    sdt.SDTProperties.Tag = 'brand-logo';

    // Load the picture and set its display size
    const picture = new wasmModule.DocPicture(doc);
    picture.LoadImage('logo.png');
    picture.Width = 160;
    picture.Height = 54;
    sdt.SDTContent.ChildObjects.Add(picture);

    // Add a note about the size
    const noteParagraph = section.AddParagraph();
    noteParagraph.Format.BeforeSpacing = 10;
    const noteRange = noteParagraph.AppendText('The size of a picture content control is measured in points; the example uses 160 × 54 points.');
    noteRange.CharacterFormat.FontName = 'Arial';
    noteRange.CharacterFormat.FontSize = 9;
    noteRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);

    // Save the result file
    const outputFileName = 'AddPictureContentControl.docx';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });
    doc.Dispose();

    // 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/vnd.openxmlformats-officedocument.wordprocessingml.document' });
    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 Picture Content Control</h1>
      <button onClick={addPictureControl}>Generate Document</button>
    </div>
  );
}

export default App;

Document after adding a picture content control:

FAQ

What is the difference between a content control and ordinary text

Ordinary text is just a run of characters in a paragraph, so a program can only find it by position or by its text content. A content control is a separate object with a type, alias, tag and lock state, whose business meaning can be read directly through SDTProperties. In Word it also indicates the fillable area with a tag or a border. For templates that need to collect data and be reused repeatedly, content controls are usually easier to maintain.

What can I do if the generated content control shows no border in Word

With the default appearance, the control looks much the same as ordinary text. Set SDTProperties.Appearance to SdtAppearance.Tags to show alias tags on both sides of the control, or to SdtAppearance.BoundingBox to show a border in Word's editing view. Appearance only affects the display; it does not change the control type or the content.

How should I choose between a text content control and a rich text content control

If the field only accepts plain text and the person filling it in should not change the font or color, choose a text content control. If formats such as bold and color have to be preserved inside the control, or the content is itself a passage with emphasis, choose a rich text content control. In code the two differ only in SDTType and in how the content fragments are organized.

Why does the size set for a picture content control differ slightly from the actual size

When both DocPicture.Width and Height are set, the picture is scaled proportionally according to its original aspect ratio, so the final size may differ from the set values by one or two points. For an exact size, set only one dimension and let the other be calculated from the ratio, or crop the source picture to the target ratio before inserting it.

Get a Free License

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

Fields such as evaluation conclusions, department names and product line ownership usually take only a limited set of values. If the person filling in the form is allowed to type freely, it is easy to end up with "R&D Department", "R&D Center" and "R&D" used side by side, and the records have to be cleaned up one by one before they can be summarized. Word's drop-down list and combo box content controls write the allowed values into the document in advance, so the person filling in the form can only pick from them, and the data format is unified at the source.

The difference between the two lies in whether values outside the preset range are allowed: a drop-down list accepts only the options in the list, while a combo box also allows the user to enter something outside it. Which one to choose depends on whether the business needs to keep exceptions.

This article uses Spire.Doc for JavaScript to create both kinds of controls in the browser, and demonstrates how to update the list items and selected value of an existing combo box. All processing is performed in WebAssembly; documents never pass through a server.

This article covers the following topics:

• Add a Drop-Down List Content Control
• Add a Combo Box Content Control
• Update Combo Box List Items and Selected Value

Both kinds of controls mount their list data through SDTProperties.ControlProperties, and SdtListItem is a single item in the list:

For installation and project setup, refer to Integrating Spire.Doc for JavaScript in a React Project. The examples below assume that Spire.Doc is installed and the WebAssembly module is initialized.

Add a Drop-Down List Content Control

A drop-down list suits fields whose values are completely fixed, such as rating levels, approval conclusions and expense categories. When creating one, first set SDTType to SdtType.DropDownList, then construct an SdtDropDownList and add each option to ListItems as an SdtListItem.

The following members are involved in adding a drop-down list content control:

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the font, create a document with the Document class and add a section, then write the title and description.
3. Create a StructureDocumentTagInline control in the paragraph and set SDTType to SdtType.DropDownList.
4. Create an SdtDropDownList, add the SdtListItem options one by one, and assign it to ControlProperties.
5. Write the text of the currently selected option into SDTContent, save the file and read it from the VFS for download.

The code for adding a drop-down list content control is as follows:

function App() {
  const addDropDownList = async () => {
    // Get the Spire.Doc WASM module
    const wasmModule = window.wasmModule?.spiredoc;

    if (!wasmModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the font
    await window.spire.FetchFileToVFS('arial.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    await window.spire.FetchFileToVFS('arialbd.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    // Create a document and add a section
    const doc = new wasmModule.Document();
    const section = doc.AddSection();

    // Add the title and subtitle
    const titleParagraph = section.AddParagraph();
    const titleRange = titleParagraph.AppendText('Supplier Rating Form');
    titleRange.CharacterFormat.FontName = 'Arial';
    titleRange.CharacterFormat.FontSize = 19;
    titleRange.CharacterFormat.Bold = true;
    titleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 15, 110, 90);
    titleParagraph.Format.AfterSpacing = 6;

    const subtitleParagraph = section.AddParagraph();
    const subtitleRange = subtitleParagraph.AppendText('Procurement Department    Q3 2026');
    subtitleRange.CharacterFormat.FontName = 'Arial';
    subtitleRange.CharacterFormat.FontSize = 9;
    subtitleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);
    subtitleParagraph.Format.AfterSpacing = 16;

    // Add the explanatory text before the control
    const paragraph = section.AddParagraph();
    paragraph.AppendText('Evaluation Result:  ');

    // Create an inline content control and add it to the paragraph
    const sdt = new wasmModule.StructureDocumentTagInline(doc);
    paragraph.ChildObjects.Add(sdt);

    // Set the control type to drop-down list
    sdt.SDTProperties.SDTType = wasmModule.SdtType.DropDownList;
    sdt.SDTProperties.Alias = 'Evaluation Result';
    sdt.SDTProperties.Tag = 'evaluation-result';
    sdt.SDTProperties.Appearance = wasmModule.SdtAppearance.Tags;

    // Build the drop-down list and add the options
    const list = new wasmModule.SdtDropDownList();
    list.ListItems.Add(new wasmModule.SdtListItem('Excellent'));
    list.ListItems.Add(new wasmModule.SdtListItem('Good'));
    list.ListItems.Add(new wasmModule.SdtListItem('Qualified'));
    list.ListItems.Add(new wasmModule.SdtListItem('Needs Improvement'));
    sdt.SDTProperties.ControlProperties = list;

    // Write the text of the currently selected option
    const content = new wasmModule.TextRange(doc);
    content.Text = list.ListItems.get_Item(1).DisplayText;
    sdt.SDTContent.ChildObjects.Add(content);

    // Add the closing note
    const noteParagraph = section.AddParagraph();
    noteParagraph.Format.BeforeSpacing = 10;
    const noteRange = noteParagraph.AppendText('A drop-down list only allows choices from the preset options, which suits fixed values such as conclusions and ratings.');
    noteRange.CharacterFormat.FontName = 'Arial';
    noteRange.CharacterFormat.FontSize = 9;
    noteRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);

    // Save the result file
    const outputFileName = 'AddDropDownListContentControl.docx';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });
    doc.Dispose();

    // 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/vnd.openxmlformats-officedocument.wordprocessingml.document' });
    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 Drop-Down List Content Control</h1>
      <button onClick={addDropDownList}>Generate Document</button>
    </div>
  );
}

export default App;

Document after adding a drop-down list content control:

Display Text and Value of an Option

SdtListItem has two constructors:

When only one argument is passed, the display text and the internal value are the same, which suits options that are themselves business terms. When two arguments are passed, the document displays the first one, while a program can read and compare the second one; setting the internal value to a stable English identifier keeps the meaning of the data unchanged even after the interface wording is adjusted.

Add a Combo Box Content Control

A combo box provides a list of candidates while allowing the person filling in the form to enter content outside the list. It suits fields such as product lines and supplier names that are "usually fixed, occasionally exceptional". The code structure is almost identical to that of the drop-down list; only the type changes to SdtType.ComboBox and the control property class to SdtComboBox.

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the font, create a document with the Document class and add a section, then write the title and description.
3. Create a StructureDocumentTagInline control in the paragraph and set SDTType to SdtType.ComboBox.
4. Create an SdtComboBox, add the candidate options, assign it to ControlProperties, and write the text of the selected option.
5. Save the result file with SaveToFile(), read it from the VFS and trigger a browser download.

The code for adding a combo box content control is as follows:

function App() {
  const addComboBox = async () => {
    // Get the Spire.Doc WASM module
    const wasmModule = window.wasmModule?.spiredoc;

    if (!wasmModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the font
    await window.spire.FetchFileToVFS('arial.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    await window.spire.FetchFileToVFS('arialbd.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    // Create a document and add a section
    const doc = new wasmModule.Document();
    const section = doc.AddSection();

    // Add the title and subtitle
    const titleParagraph = section.AddParagraph();
    const titleRange = titleParagraph.AppendText('Product Line Registration Form');
    titleRange.CharacterFormat.FontName = 'Arial';
    titleRange.CharacterFormat.FontSize = 19;
    titleRange.CharacterFormat.Bold = true;
    titleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 15, 110, 90);
    titleParagraph.Format.AfterSpacing = 6;

    const subtitleParagraph = section.AddParagraph();
    const subtitleRange = subtitleParagraph.AppendText('Marketing Department    November 2026');
    subtitleRange.CharacterFormat.FontName = 'Arial';
    subtitleRange.CharacterFormat.FontSize = 9;
    subtitleRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);
    subtitleParagraph.Format.AfterSpacing = 16;

    // Add the explanatory text before the control
    const paragraph = section.AddParagraph();
    paragraph.AppendText('Partner Product Line:  ');

    // Create an inline content control and add it to the paragraph
    const sdt = new wasmModule.StructureDocumentTagInline(doc);
    paragraph.ChildObjects.Add(sdt);

    // Set the control type to combo box
    sdt.SDTProperties.SDTType = wasmModule.SdtType.ComboBox;
    sdt.SDTProperties.Alias = 'Partner Product Line';
    sdt.SDTProperties.Tag = 'product-line';
    sdt.SDTProperties.Appearance = wasmModule.SdtAppearance.Tags;

    // Build the combo box and add the candidates
    const combo = new wasmModule.SdtComboBox();
    combo.ListItems.Add(new wasmModule.SdtListItem('Office Suite'));
    combo.ListItems.Add(new wasmModule.SdtListItem('Document Services'));
    combo.ListItems.Add(new wasmModule.SdtListItem('Data Platform'));
    combo.ListItems.Add(new wasmModule.SdtListItem('Presentation Components'));
    sdt.SDTProperties.ControlProperties = combo;

    // Write the text of the currently selected option
    const content = new wasmModule.TextRange(doc);
    content.Text = combo.ListItems.get_Item(1).DisplayText;
    sdt.SDTContent.ChildObjects.Add(content);

    // Add the closing note
    const noteParagraph = section.AddParagraph();
    noteParagraph.Format.BeforeSpacing = 10;
    const noteRange = noteParagraph.AppendText('A combo box keeps the preset options available while allowing content outside the list.');
    noteRange.CharacterFormat.FontName = 'Arial';
    noteRange.CharacterFormat.FontSize = 9;
    noteRange.CharacterFormat.TextColor = wasmModule.Color.FromArgb(255, 89, 89, 89);

    // Save the result file
    const outputFileName = 'AddComboBoxContentControl.docx';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });
    doc.Dispose();

    // 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/vnd.openxmlformats-officedocument.wordprocessingml.document' });
    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 Combo Box Content Control</h1>
      <button onClick={addComboBox}>Generate Document</button>
    </div>
  );
}

export default App;

Document after adding a combo box content control:

Update Combo Box List Items and Selected Value

In practice, options change over time: a product line is retired and has to be removed from the list; a new product line has to be added; and for some forms a recommended value has to be selected in advance. All of these operations can be performed on a loaded document without regenerating the whole file.

To update the control, first iterate over the paragraphs and tables in the body, find the control whose DocumentObjectType is StructureDocumentTagInline and whose type is ComboBox, then call the add and remove methods of ListItems on its ControlProperties. The example reads ComboBox.docx from public/data, so put that file in the project's public/data directory before running it.

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the font, read ComboBox.docx into the VFS and load it as a Document.
3. Iterate over the body objects of each section and the child objects of each paragraph, and filter out the combo box content controls.
4. Remove the old option with RemoveAt, append a new one with Add, then compare by Value and set SelectedValue.
5. Save the result file with SaveToFile(), read it from the VFS and trigger a browser download.

The code for updating the combo box list items and selected value is as follows:

function App() {
  const updateComboBoxItems = async () => {
    // Get the Spire.Doc WASM module
    const wasmModule = window.wasmModule?.spiredoc;

    if (!wasmModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the document to be processed
    await window.spire.FetchFileToVFS('ComboBox.docx', '', `${process.env.PUBLIC_URL}/data/`);

    const doc = new wasmModule.Document();
    doc.LoadFromFile('ComboBox.docx');

    // Iterate over the sections and find combo box content controls
    for (let s = 0; s < doc.Sections.Count; s++) {
      const section = doc.Sections.get_Item(s);
      for (let i = 0; i < section.Body.ChildObjects.Count; i++) {
        const obj = section.Body.ChildObjects.get_Item(i);
        if (obj.DocumentObjectType !== wasmModule.DocumentObjectType.Paragraph) continue;

        for (let j = 0; j < obj.ChildObjects.Count; j++) {
          const child = obj.ChildObjects.get_Item(j);
          if (child.DocumentObjectType !== wasmModule.DocumentObjectType.StructureDocumentTagInline) continue;
          if (child.SDTProperties.SDTType !== wasmModule.SdtType.ComboBox) continue;

          const combo = child.SDTProperties.ControlProperties;

          // Remove the old option at index 1 and append a new one
          combo.ListItems.RemoveAt(1);
          combo.ListItems.Add(new wasmModule.SdtListItem('Smart Documents', 'Smart Documents'));

          // Find the new option by Value and set it as the selected value
          for (let k = 0; k < combo.ListItems.Count; k++) {
            const item = combo.ListItems.get_Item(k);
            if (item.Value === 'Smart Documents') {
              combo.ListItems.SelectedValue = item;
            }
          }
        }
      }
    }

    // Save the result file
    const outputFileName = 'UpdateComboBoxItems.docx';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });
    doc.Dispose();

    // 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/vnd.openxmlformats-officedocument.wordprocessingml.document' });
    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>Update Combo Box List Items and Selected Value</h1>
      <button onClick={updateComboBoxItems}>Generate Document</button>
    </div>
  );
}

export default App;

The comparison before and after processing is shown below; the left image is the original document and the right image is the document after updating:

Traversal Order When Locating the Control

The example scans only the inline controls in paragraphs directly under the body, which is the most common location. If a control is inside a table cell, first check whether the object is a Table, then walk row by row and cell by cell into Cell.ChildObjects to find it; if the control is a block-level StructureDocumentTag, compare it directly at the Body.ChildObjects level. When traversing, check DocumentObjectType before reading properties so that ordinary paragraphs are not treated as controls by mistake.

FAQ

How to Choose Between a Drop-Down List and a Combo Box

Cause: The two controls differ mainly in whether values outside the preset options are allowed, and this has to be decided together with the business rules for the field.

Solution: If the field's values must be strictly limited to the preset range, use a drop-down list; if the list only provides common candidates and the business allows content outside it, use a combo box. A drop-down list is better for fields such as ratings, statuses and categories that need a consistent vocabulary, while a combo box is better for fields such as names and product lines that may expand with the business.

Why the Text Displayed by the Control Does Not Change After Setting SelectedValue

Cause: SelectedValue must be assigned an SdtListItem object; assigning a string directly has no effect.

Solution: In the example, iterate over ListItems, compare Value to find the target item, then assign that item object to SelectedValue. After the change, save the file and Word displays the selected item.

Why the Wrong Item Is Selected After RemoveAt

Cause: After RemoveAt deletes an element, the indexes of the remaining options shift forward. If you delete first and then access by the original index, you may get a different option.

Solution: After deleting, iterate over ListItems again and find the target item by Value or DisplayText, rather than reusing the index from before the deletion.

How to Select an Option by the Text the User Sees

Cause: Value and DisplayText can be different, so which one to compare against depends on what the business treats as authoritative.

Solution: If the interface text is authoritative, change the comparison condition to item.DisplayText === 'Smart Documents'; if a stable internal identifier is authoritative, keep comparing Value. Do not mix the two, or selection may fail after the wording is adjusted.

Get a Free License

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

Word count, character count, paragraph count, line count and page count measure the content size and the layout result of a Word document: the word count reflects the total volume of text, the character count is used to account for length, the paragraph count shows the structure of the content, and the line count and page count are directly related to the print layout. When this kind of counting is performed on a web page, uploading the file to a server adds an extra transfer, while relying on desktop software makes it difficult to fit the process into an automated workflow.

This article reads these statistics in the browser with Spire.Doc for JavaScript. The whole process runs in the browser on WebAssembly, requires no Office installation and depends on no backend service, and the file always remains on the user's device.

This article covers the following topics:

• Count the Words, Characters, Paragraphs, Lines and Pages of a Word Document
• Count the Words and Characters of a Specified Paragraph

For installation and project setup, refer to Integrating Spire.Doc for JavaScript in a React Project. The examples below assume that Spire.Doc is installed and the WebAssembly module is initialized.

Count the Words, Characters, Paragraphs, Lines and Pages of a Word Document

The word count, character count, paragraph count, line count and page count of a Word document are read mainly through Document.BuiltinDocumentProperties. The property returns a BuiltinDocumentProperties object, and the statistics correspond to its properties as follows:

The statistics in the built-in properties come from the statistics saved inside the document. For a newly created document, or a document generated by another tool into which statistics have not yet been written, the word count, character count and paragraph count may be 0, so the example calls Document.UpdateWordCount() before reading to recalculate these three values. The line count and page count are layout statistics; UpdateWordCount() does not recalculate them, and their values depend on the statistics already saved in the document.

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the sample document and the font into the virtual file system (VFS), create a Document object and load the file.
3. Call Document.UpdateWordCount() to recalculate the word count, character count and paragraph count.
4. Read each statistic through Document.BuiltinDocumentProperties.
5. Assemble the statistics as text, save them as a TXT file and trigger a browser download.

The code for counting the words, characters, paragraphs, lines and pages of a Word document is as follows:

function App() {
  const countDocument = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Make sure the WASM module has fully loaded
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the sample document and the font into VFS
    await window.spire.FetchFileToVFS('Sample Document.docx', "", `${process.env.PUBLIC_URL}/data/`);
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', "/Library/Fonts/", `${process.env.PUBLIC_URL}/font/`);

    // Create a Document instance and load the document
    const doc = new docModule.Document();
    doc.LoadFromFile('Sample Document.docx');

    // Recalculate the word count, character count and paragraph count
    doc.UpdateWordCount();

    // Get the built-in document properties
    const properties = doc.BuiltinDocumentProperties;

    // Read each statistic
    const wordCount = properties.WordCount;
    const charCount = properties.CharCount;
    const charCountWithSpace = properties.CharCountWithSpace;
    const paragraphCount = properties.ParagraphCount;
    const lineCount = properties.LinesCount;
    const pageCount = properties.PageCount;

    // Assemble the results
    const report = [
      'Word count: ' + wordCount,
      'Characters (no spaces): ' + charCount,
      'Characters (with spaces): ' + charCountWithSpace,
      'Paragraphs: ' + paragraphCount,
      'Lines: ' + lineCount,
      'Pages: ' + pageCount,
    ].join('\r\n');

    doc.Dispose();

    // Save the results as a TXT file and trigger the download
    const outputFileName = 'Word Count Results.txt';
    const blob = new Blob([report], { type: 'text/plain;charset=utf-8' });
    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>Count Word Document Statistics</h1>
      <button onClick={countDocument}>
        Count Document Statistics
      </button>
    </div>
  );
}

export default App;

After the code above runs, the downloaded "Word Count Results.txt" contains the following:

Count the Words and Characters of a Specified Paragraph

The words and characters of a specified paragraph in a Word document can be read with the three properties Paragraph.WordCount, Paragraph.CharCount and Paragraph.CharCountIncludeSpace. Unlike the built-in properties of the whole document, paragraph-level statistics are calculated directly from the paragraph content, and the document statistics do not have to be updated before reading.

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the sample document and the font into the virtual file system (VFS), create a Document object and load the file.
3. Get the second paragraph in the first section through Document.Sections.get_Item(0).Paragraphs.get_Item(1).
4. Read the statistics of that paragraph through Paragraph.WordCount, Paragraph.CharCount and Paragraph.CharCountIncludeSpace.
5. Assemble the statistics as text, save them as a TXT file and trigger a browser download.

The code for counting the words and characters of a specified paragraph in a Word document is as follows:

function App() {
  const countParagraph = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Make sure the WASM module has fully loaded
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the sample document and the font into VFS
    await window.spire.FetchFileToVFS('Sample Document.docx', "", `${process.env.PUBLIC_URL}/data/`);
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', "/Library/Fonts/", `${process.env.PUBLIC_URL}/font/`);

    // Create a Document instance and load the document
    const doc = new docModule.Document();
    doc.LoadFromFile('Sample Document.docx');

    // Get the second paragraph in the first section (index starts at 0)
    const paragraph = doc.Sections.get_Item(0).Paragraphs.get_Item(1);

    // Read the words and characters of that paragraph
    const wordCount = paragraph.WordCount;
    const charCount = paragraph.CharCount;
    const charCountIncludeSpace = paragraph.CharCountIncludeSpace;

    // Assemble the results
    const report = [
      'Word count: ' + wordCount,
      'Characters (no spaces): ' + charCount,
      'Characters (with spaces): ' + charCountIncludeSpace,
    ].join('\r\n');

    doc.Dispose();

    // Save the results as a TXT file and trigger the download
    const outputFileName = 'Paragraph Statistics.txt';
    const blob = new Blob([report], { type: 'text/plain;charset=utf-8' });
    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>Paragraph Statistics</h1>
      <button onClick={countParagraph}>
        Count Paragraph Statistics
      </button>
    </div>
  );
}

export default App;

After the code above runs, the downloaded "Paragraph Statistics.txt" contains the following:

FAQ

Why is the calculated word count or character count 0

Cause: The statistics in the built-in properties come from the statistics saved inside the document. For a newly created document, or a document generated by some tools without statistics written into it, the word count, character count and paragraph count read back may be 0.

Solution: The example calls Document.UpdateWordCount() before reading, which recalculates these three values from the current content; the call updates the statistics without modifying the document body.

Why do the line count and page count differ from what Word displays

Cause: The line count and page count are layout statistics kept in the built-in properties of the document, and Document.UpdateWordCount() does not recalculate them, so the values returned are those already saved in the document. When the content has been edited but the document has not been saved again, these values may remain in their previous state and differ from what Word currently displays.

Solution: To verify them, open the "Word Count" dialog in Word; for the words and characters of a paragraph, read Paragraph.WordCount and Paragraph.CharCount directly.

What is the difference between the word count and the two character counts

Cause: The three statistics measure different things: WordCount returns the word count of the document, while CharCount and CharCountWithSpace return the character count without and with spaces respectively, both including punctuation.

Solution: When accounting for length or layout capacity, use the character count with spaces, that is, CharCountWithSpace.

How do I count the words and characters of other paragraphs

Cause: The indexes of Sections.get_Item() and Paragraphs.get_Item() both start at 0, and the Paragraphs.get_Item(1) in the example points to the second paragraph in the first section.

Solution: Change the index to count the corresponding paragraph; check Paragraphs.Count before reading to avoid an index out of range.

Get a Free License

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

Microsoft Word's built-in watermark feature can place only one watermark at a time, and its position and number are fixed by the built-in layout, so it cannot tile the whole page with multiple rows and columns. For contracts, internal documents and presentation drafts that need full-page coverage, the watermark can be implemented by adding a shape or a picture to the header and then cloning it by row and column.

This article adds multi-row, multi-column text watermarks and image watermarks to Word documents in the browser with Spire.Doc for JavaScript. The whole process runs in the browser on WebAssembly, requires no Office installation and depends on no backend service, and the file always remains on the user's device.

This article covers the following topics:

• Add Multi-Row Text Watermarks
• Add Multi-Row Image Watermarks
• Adjust the Tiling Rows, Columns and Spacing

The two kinds of watermarks are implemented as follows:

For installation and project setup, refer to Integrating Spire.Doc for JavaScript in a React Project. The examples below assume that Spire.Doc is installed and the WebAssembly module is initialized. The examples read Sample.docx and logo.png from the project's public/data directory and the font file from the public/font directory, so put the corresponding files into these two directories before running them.

Add Multi-Row Text Watermarks

To add a multi-row, multi-column text watermark, a WordArt shape is created in the header, then cloned in a loop over rows and columns, and each copy is given its own vertical and horizontal coordinates. The watermark object lives in the header, so it is repeated on every page together with the header and does not have to be added page by page.

The following members are involved in adding multi-row text watermarks:

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the sample document and the font into the virtual file system (VFS), create a Document object and load the document.
3. Create a ShapeObject, set its shape type to ShapeType.TextPlainText, and set its width, height, rotation angle, WordArt content, font, fill color and outline color.
4. Iterate over every section of the document, get the header through HeadersFooters.Header, and add a paragraph with AddParagraph().
5. Clone the shape with Clone() in a loop over rows and columns, give each copy its own VerticalPosition and HorizontalPosition, and add it to the ChildObjects of the header paragraph.
6. Save the result file with SaveToFile(), read it from the VFS and trigger a browser download.

The code for adding multi-row text watermarks is as follows:

function App() {
  const addTextWatermark = async () => {
    // Get the Spire.Doc WASM module
    const wasmModule = window.wasmModule?.spiredoc;

    if (!wasmModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the sample document and the font
    await window.spire.FetchFileToVFS('Sample.docx', '', `${process.env.PUBLIC_URL}/data/`);
    await window.spire.FetchFileToVFS('arial.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    await window.spire.FetchFileToVFS('arialbd.ttf', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    // Create a Document instance and load the document
    const doc = new wasmModule.Document();
    doc.LoadFromFile('Sample.docx');

    // Create a WordArt shape and set its size, position, rotation and style
    let shape = new wasmModule.ShapeObject(doc, wasmModule.ShapeType.TextPlainText);
    shape.Width = 60;
    shape.Height = 15;
    shape.VerticalPosition = 25;
    shape.HorizontalPosition = 20;
    shape.Rotation = 320;
    shape.WordArt.Text = 'INTERNAL USE';
    shape.WordArt.FontFamily = 'Arial';
    shape.FillColor = wasmModule.Color.FromArgb(255, 255, 0, 0);
    shape.StrokeColor = wasmModule.Color.FromArgb(255, 255, 0, 0);

    // Iterate over all sections and add the watermark to the header of each section
    for (let n = 0; n < doc.Sections.Count; n++) {
      const section = doc.Sections.get_Item(n);
      const header = section.HeadersFooters.Header;
      const paragraph = header.AddParagraph();

      // 5 rows and 6 columns: clone the shape and set the coordinates of each copy
      for (let i = 0; i < 5; i++) {
        for (let j = 0; j < 6; j++) {
          shape = shape.Clone();
          shape.VerticalPosition = 50 + 150 * i;
          shape.HorizontalPosition = 20 + 85 * j;
          paragraph.ChildObjects.Add(shape);
        }
      }
    }

    // Save the result file
    const outputFileName = 'AddTextWatermark.docx';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });
    doc.Dispose();

    // 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/vnd.openxmlformats-officedocument.wordprocessingml.document' });
    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 Multi-Row Text Watermarks</h1>
      <button onClick={addTextWatermark}>Generate Document</button>
    </div>
  );
}

export default App;

After adding multi-row, multi-column text watermarks, the document looks like this:

Add Multi-Row Image Watermarks

To add a multi-row, multi-column image watermark, a picture is loaded into the header, then cloned by row and column and given its own coordinates. Compared with a text watermark, the appearance of an image watermark is determined by the picture itself, and the code only has to control the wrapping style and the arrangement of the copies.

The following members are involved in adding multi-row image watermarks:

The specific steps are as follows:

1. Get the Spire.Doc WASM module and confirm that it is ready.
2. Load the sample document and the watermark image into the virtual file system (VFS), create a Document object and load the document.
3. Iterate over every section of the document, get the header through HeadersFooters.Header, and add a paragraph with AddParagraph().
4. Create a DocPicture, call LoadImage() to load the watermark image, and set TextWrappingStyle to TextWrappingStyle.Behind.
5. Clone the picture with Clone() in a loop over rows and columns, give each copy its own VerticalPosition and HorizontalPosition, and add it to the ChildObjects of the header paragraph.
6. Save the result file with SaveToFile(), read it from the VFS and trigger a browser download.

The code for adding multi-row image watermarks is as follows:

function App() {
  const addImageWatermark = async () => {
    // Get the Spire.Doc WASM module
    const wasmModule = window.wasmModule?.spiredoc;

    if (!wasmModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load the sample document and the watermark image
    await window.spire.FetchFileToVFS('Sample.docx', '', `${process.env.PUBLIC_URL}/data/`);
    await window.spire.FetchFileToVFS('logo.png', '', `${process.env.PUBLIC_URL}/data/`);

    // Create a Document instance and load the document
    const doc = new wasmModule.Document();
    doc.LoadFromFile('Sample.docx');

    // Iterate over all sections and add the watermark to the header of each section
    for (let n = 0; n < doc.Sections.Count; n++) {
      const section = doc.Sections.get_Item(n);
      const header = section.HeadersFooters.Header;
      const paragraph = header.AddParagraph();

      // Create a picture object and load the watermark image
      const picture = new wasmModule.DocPicture(doc);
      picture.LoadImage('logo.png');
      picture.TextWrappingStyle = wasmModule.TextWrappingStyle.Behind;

      // 5 rows and 3 columns: clone the picture and set the coordinates of each copy
      for (let p = 0; p < 5; p++) {
        for (let q = 0; q < 3; q++) {
          const pic = picture.Clone();
          pic.VerticalPosition = 50 + 150 * p;
          pic.HorizontalPosition = 10 + 150 * q;
          paragraph.ChildObjects.Add(pic);
        }
      }
    }

    // Save the result file
    const outputFileName = 'AddImageWatermark.docx';
    doc.SaveToFile({ fileName: outputFileName, fileFormat: wasmModule.FileFormat.Docx2013 });
    doc.Dispose();

    // 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/vnd.openxmlformats-officedocument.wordprocessingml.document' });
    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 Multi-Row Image Watermarks</h1>
      <button onClick={addImageWatermark}>Generate Document</button>
    </div>
  );
}

export default App;

After adding multi-row, multi-column image watermarks, the document looks like this:

Adjust the Tiling Rows, Columns and Spacing

Adjusting the tiling rows, columns and spacing means changing the loop counts and the two coefficients in the coordinate formula: the number of rows and columns determines how many watermarks there are, while the row gap and column gap determine the distance between neighboring watermarks. Together they decide how dense the tiling is on the page.

The coordinate formula used for tiling is as follows:

The coordinates of each watermark are calculated as follows:

• VerticalPosition = start vertical coordinate + row gap × row index
• HorizontalPosition = start horizontal coordinate + column gap × column index

The specific steps are as follows:

1. Estimate the width and height available for the watermarks from the page size and the page margins.
2. Decide the number of rows and columns, and the start coordinates of the first row and first column.
3. Change the loop counts and the row gap and column gap in the coordinate formula, and adjust the width and height of the shape as needed.
4. Save the file and preview it, then fine-tune the spacing according to the actual result.

The code for adjusting the tiling rows, columns and spacing is as follows. The example uses 4 rows and 5 columns, a row gap of 180 points and a column gap of 100 points, and changes the watermark to dark gray:

// Number of rows, columns and the spacing
const rows = 4;
const cols = 5;
const rowGap = 180;
const colGap = 100;

// Create the base shape and clone it later with Clone()
const base = new wasmModule.ShapeObject(doc, wasmModule.ShapeType.TextPlainText);
base.Width = 80;
base.Height = 20;
base.Rotation = 315;
base.WordArt.Text = 'CONFIDENTIAL';
base.WordArt.FontFamily = 'Arial';
base.FillColor = wasmModule.Color.FromArgb(255, 70, 70, 70);
base.StrokeColor = wasmModule.Color.FromArgb(255, 70, 70, 70);

for (let n = 0; n < doc.Sections.Count; n++) {
  const header = doc.Sections.get_Item(n).HeadersFooters.Header;
  const paragraph = header.AddParagraph();

  for (let i = 0; i < rows; i++) {
    for (let j = 0; j < cols; j++) {
      const shape = base.Clone();
      shape.VerticalPosition = 40 + rowGap * i;
      shape.HorizontalPosition = 20 + colGap * j;
      paragraph.ChildObjects.Add(shape);
    }
  }
}

After adjusting the rows, columns and spacing, the text watermark looks like this:

FAQ

Why does the watermark not appear on the first page

Cause: Headers are set per section. The example writes to HeadersFooters.Header, which applies to the normal pages of the section. When a document uses "Different first page", the first page uses HeadersFooters.FirstPageHeader instead; when it uses "Different odd and even pages", even pages use HeadersFooters.EvenHeader. The sample document uses neither option, so the watermark appears on every page.

Solution: Add the watermark to HeadersFooters.FirstPageHeader or HeadersFooters.EvenHeader as well when the corresponding option is enabled.

Why do the rightmost columns fall outside the page

Cause: HorizontalPosition is measured in points and starts from the left page margin. With text watermarks 60 points wide, a column gap of 85 points and 6 columns, the right edge of the last column is about 20 + 85 × 5 + 60 = 505 points, which is already close to the right edge of the page once the left margin is added. If the column gap or the number of columns is increased further, the rightmost objects go beyond the page.

Solution: Before adjusting, estimate the total width as "start coordinate + gap × (count − 1) + object width" and compare it with the page width.

Why does the set position differ from the actual position on the page

Cause: Shapes in the header are positioned absolutely: horizontally from the left page margin and vertically from the top of the header area. The sample document has a left margin of 90 points and the header sits 36 points from the top of the page, so with HorizontalPosition = 20 the watermark actually appears at about 110 points from the left edge of the page.

Solution: After changing the template or adjusting the page margins, re-estimate the start coordinates.

Do duplicated image watermarks significantly increase the file size

Usually not. The copies share the same image: Clone() duplicates the picture object and the layout properties, while the image itself is stored only once in the document. The example produces 15 image watermarks, and the word/media/ directory of the docx still contains a single image file, which the other copies reference. The increase in file size comes mainly from the shape and positioning data rather than from the image data.

What if the image watermark covers the body text

The example places the picture behind the body text with TextWrappingStyle.Behind, so the pictures have a negative z-order in the generated document and the body text stays on top. If the watermark is still too prominent, reduce its opacity or use a lighter version when preparing the image; the example uses a semi-transparent, light-colored PNG.

Get a Free License

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