Add Custom Data to PDF Form Fields in React PDF Viewer

25 Feb 202611 minutes to read

The Syncfusion React PDF Viewer allows you to attach custom application-specific data to form fields by using the customData property. This enables you to associate business identifiers, tags, validation hints, or workflow metadata with form fields.

Custom data remains associated with the form field for the duration of the viewer session and can be accessed or updated whenever the field is queried or modified.

This article explains how to:

Add custom data when creating form fields
Define default custom data for fields created using the UI
Update or replace custom data for existing fields
Read custom data from form fields
Apply best practices when using custom data

Key Points

customData is a free form object; you control its structure.
Use only serializable values such as objects, arrays, strings, numbers, and booleans.
Custom data does not affect the field appearance or behavior unless consumed by your application logic.

Add Custom Data While Creating PDF Form Fields

Attach custom data at field creation by passing a customData object in the settings parameter of addFormField().

index.js
import * as ReactDOM from 'react-dom/client';
import React, { useRef } from 'react';
import './index.css';
import { PdfViewerComponent, Toolbar, Magnification, Navigation, LinkAnnotation, BookmarkView, ThumbnailView, Print, TextSelection, Annotation, TextSearch, FormFields, FormDesigner, Inject } from '@syncfusion/ej2-react-pdfviewer';

export function App() {
  const viewerRef = useRef(null);

  const onDocumentLoad = () => {
    const meta = { businessId: 'C-1024', tags: ['profile', 'kiosk'], requiredRole: 'admin' };
    viewerRef.current?.formDesignerModule.addFormField('Textbox', {
      name: 'Email',
      bounds: { X: 146, Y: 229, Width: 200, Height: 24 },
      // Attach any custom metadata your app needs
      customData: meta
    });
  };

  return (
    <div>
      <div className='control-section'>
        <PdfViewerComponent
          ref={viewerRef}
          id="container"
          documentPath="https://cdn.syncfusion.com/content/pdf/form-designer.pdf"
          resourceUrl="https://cdn.syncfusion.com/ej2/31.2.2/dist/ej2-pdfviewer-lib"
          style=
          documentLoad={onDocumentLoad}
        >
          <Inject services={[Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, BookmarkView, ThumbnailView,
            Print, TextSelection, TextSearch, FormFields, FormDesigner]} />
        </PdfViewerComponent>
      </div>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById('sample'));
root.render(<App />);

Set Default Custom Data for PDF Form Fields Added Using UI

When form fields are added via the Form Designer toolbar, define default customData so newly created fields inherit it. Default custom data is configured using per-field settings objects such as:

index.js
import * as ReactDOM from 'react-dom/client';
import * as React from 'react';
import './index.css';
import { PdfViewerComponent, Toolbar, Magnification, Navigation, LinkAnnotation, BookmarkView, ThumbnailView, Print, TextSelection, Annotation, TextSearch, FormFields, FormDesigner, Inject } from '@syncfusion/ej2-react-pdfviewer';

export function App() {
  const defaultTextFieldSettings = {
    name: 'Textbox',
    customData: { group: 'contact', createdBy: 'designer', requiredRole: 'user' }
  };
  const defaultCheckBoxFieldSettings = {
    name: 'Checkbox',
    customData: { consentType: 'marketing', defaultChecked: false }
  };
  return (
    <div>
      <div className='control-section'>
        <PdfViewerComponent
          id="container"
          documentPath="https://cdn.syncfusion.com/content/pdf/form-designer.pdf"
          resourceUrl="https://cdn.syncfusion.com/ej2/31.2.2/dist/ej2-pdfviewer-lib"
          style=
          // Example: default custom data for all new Textbox fields added from the toolbar
          textFieldSettings={defaultTextFieldSettings}
          checkBoxFieldSettings={defaultCheckBoxFieldSettings}
        >
          <Inject services={[Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, BookmarkView, ThumbnailView,
            Print, TextSelection, TextSearch, FormFields, FormDesigner]} />
        </PdfViewerComponent>
      </div>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById('sample'));
root.render(<App />);

Update or Replace PDF Form Field Custom Data

Modify an existing field’s customData by using the updateFormField() method. The field may be identified by its object reference or field ID.

index.js
import * as ReactDOM from 'react-dom/client';
import React, { useRef } from 'react';
import './index.css';
import { PdfViewerComponent, Toolbar, Magnification, Navigation, LinkAnnotation, BookmarkView, ThumbnailView, Print, TextSelection, Annotation, TextSearch, FormFields, FormDesigner, Inject } from '@syncfusion/ej2-react-pdfviewer';

export function App() {
  const viewerRef = useRef(null);

  const updateFirstField = () => {
    const fields = viewerRef.current?.formFieldCollection || [];
    if (!fields.length) { return; }
    const target = fields[0];
    viewerRef.current?.formDesignerModule.updateFormField(target, {
      customData: { group: 'profile', flags: ['pii', 'masked'], updatedAt: Date.now() }
    });
  };

  return (
    <div>
      <div className='control-section'>
        <button onClick={updateFirstField}>Update First Field Custom Data</button>
        <PdfViewerComponent
          ref={viewerRef}
          id="container"
          documentPath="https://cdn.syncfusion.com/content/pdf/form-designer.pdf"
          resourceUrl="https://cdn.syncfusion.com/ej2/31.2.2/dist/ej2-pdfviewer-lib"
          style=
        >
          <Inject services={[Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, BookmarkView, ThumbnailView,
            Print, TextSelection, TextSearch, FormFields, FormDesigner]} />
        </PdfViewerComponent>
      </div>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById('sample'));
root.render(<App />);

Tip:
Merge new values into the existing customData object before calling updateFormField() to avoid unintentionally overwriting existing metadata.

Read Custom Data from PDF Form Fields

Access the customData property from any form field at any point in the application flow, for example:

after the document is loaded
during save or submit operations
while performing validation or conditional routing

index.js
import * as ReactDOM from 'react-dom/client';
import React, { useRef } from 'react';
import './index.css';
import { PdfViewerComponent, Toolbar, Magnification, Navigation, LinkAnnotation, BookmarkView, ThumbnailView, Print, TextSelection, Annotation, TextSearch, FormFields, FormDesigner, Inject } from '@syncfusion/ej2-react-pdfviewer';

export function App() {
  const viewerRef = useRef(null);

  const onDocumentLoad = () => {
    const fields = viewerRef.current?.formFieldCollection || [];
    fields.forEach((f) => {
      console.log('Field', f.name, 'customData:', f.customData);
    });
  };

  return (
    <div>
      <div className='control-section'>
        <PdfViewerComponent
          ref={viewerRef}
          id="container"
          documentPath="https://cdn.syncfusion.com/content/pdf/form-designer.pdf"
          resourceUrl="https://cdn.syncfusion.com/ej2/31.2.2/dist/ej2-pdfviewer-lib"
          style=
          documentLoad={onDocumentLoad}
        >
          <Inject services={[Toolbar, Magnification, Navigation, Annotation, LinkAnnotation, BookmarkView, ThumbnailView,
            Print, TextSelection, TextSearch, FormFields, FormDesigner]} />
        </PdfViewerComponent>
      </div>
    </div>
  );
}

const root = ReactDOM.createRoot(document.getElementById('sample'));
root.render(<App />);

Best Practices

Treat customData as application metadata, not display data.
Use it to drive business rules, validation logic, and workflow decisions.
Keep the data minimal and structured for easy processing.
When cloning or copying form fields, ensure customData is copied or updated as required.

View Sample on GitHub

Search docs

Ask HelpBot