Add Custom Data to PDF Form Fields in Angular PDF Viewer

2 Feb 202611 minutes to read

The Syncfusion Angular 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.

The custom data remains linked to the form field throughout the viewer session and can be accessed or updated whenever the field is queried or modified.

This page 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

You can attach custom data at the time of field creation by passing a customData object in the settings parameter of addFormField().

Standalone
import { Component, AfterViewInit, ViewChild } from '@angular/core';
import {
  ToolbarService,
  MagnificationService,
  NavigationService,
  AnnotationService,
  TextSelectionService,
  TextSearchService,
  FormFieldsService,
  FormDesignerService,
  PdfViewerModule,
} from '@syncfusion/ej2-angular-pdfviewer';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [PdfViewerModule],
  template: `
    <div class="content-wrapper">
      <ejs-pdfviewer 
        #pdfViewer
        [resourceUrl]="resourceUrl"
        [documentPath]="document"
        style="height: 640px; display: block;">
      </ejs-pdfviewer>
    </div>
  `,
  providers: [
    ToolbarService,
    MagnificationService,
    NavigationService,
    AnnotationService,
    TextSelectionService,
    TextSearchService,
    FormFieldsService,
    FormDesignerService,
  ],
})
export class AppComponent implements AfterViewInit {
  @ViewChild('pdfViewer') public pdfviewer: any;
  public document: string =
    'https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf';
  public resourceUrl: string =
    'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib';

  ngAfterViewInit(): void {
    this.pdfviewer.documentLoad = () => {
      const meta = { businessId: 'C-1024', tags: ['profile','kiosk'], requiredRole: 'admin' };
      this.pdfviewer.formDesignerModule.addFormField('Textbox', {
        name: 'Email',
        bounds: { X: 146, Y: 229, Width: 200, Height: 24 },
        customData: meta
      } as any);
    };
  }
}

Set Default Custom Data for PDF Form Fields Added Using UI

When users add form fields using the Form Designer toolbar, you can define default customData so that newly created fields automatically inherit it. Default custom data can be configured using per-field settings objects such as:

Standalone
import { Component, AfterViewInit, ViewChild } from '@angular/core';
import {
  ToolbarService,
  MagnificationService,
  NavigationService,
  AnnotationService,
  TextSelectionService,
  TextSearchService,
  FormFieldsService,
  FormDesignerService,
  PdfViewerModule,
} from '@syncfusion/ej2-angular-pdfviewer';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [PdfViewerModule],
  template: `
    <div class="content-wrapper">
      <ejs-pdfviewer 
        #pdfViewer
        [resourceUrl]="resourceUrl"
        [documentPath]="document"
        style="height: 640px; display: block;">
      </ejs-pdfviewer>
    </div>
  `,
  providers: [
    ToolbarService,
    MagnificationService,
    NavigationService,
    AnnotationService,
    TextSelectionService,
    TextSearchService,
    FormFieldsService,
    FormDesignerService,
  ],
})
export class AppComponent implements AfterViewInit {
  @ViewChild('pdfViewer') public pdfviewer: any;
  public document: string =
    'https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf';
  public resourceUrl: string =
    'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib';

  ngAfterViewInit(): void {
    // ...viewer initialization as above...
    // Example for texbox defaults
    this.pdfviewer.textFieldSettings = {
      name: 'Textbox',
      customData: { group: 'contact', createdBy: 'designer', requiredRole: 'user' }
    } as any;

    // Example for checkbox defaults
    this.pdfviewer.checkBoxFieldSettings = {
      name: 'Checkbox',
      customData: { consentType: 'marketing', defaultChecked: false }
    } as any;
  }
}

Update or Replace PDF Form Field Custom Data

You can modify the customData of an existing form field by using the updateFormField() method. The field can be identified using either its object reference or field ID.

Standalone
import { Component, AfterViewInit, ViewChild } from '@angular/core';
import {
  ToolbarService,
  MagnificationService,
  NavigationService,
  AnnotationService,
  TextSelectionService,
  TextSearchService,
  FormFieldsService,
  FormDesignerService,
  PdfViewerModule,
} from '@syncfusion/ej2-angular-pdfviewer';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [PdfViewerModule],
  template: `
    <div class="content-wrapper">
      <ejs-pdfviewer 
        #pdfViewer
        [resourceUrl]="resourceUrl"
        [documentPath]="document"
        style="height: 640px; display: block;">
      </ejs-pdfviewer>
    </div>
  `,
  providers: [
    ToolbarService,
    MagnificationService,
    NavigationService,
    AnnotationService,
    TextSelectionService,
    TextSearchService,
    FormFieldsService,
    FormDesignerService,
  ],
})
export class AppComponent implements AfterViewInit {
  @ViewChild('pdfViewer') public pdfviewer: any;
  public document: string =
    'https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf';
  public resourceUrl: string =
    'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib';

  ngAfterViewInit(): void {
    // Retrieve existing fields
    const fields = this.pdfviewer.retrieveFormFields();
    const target = fields.find((f: any) => f.name === 'Email');

    if (target) {
      // Merge with existing customData to avoid overwriting
      const merged = Object.assign({}, target.customData || {}, { updatedAt: Date.now(), verified: true });
      this.pdfviewer.formDesignerModule.updateFormField(target, { customData: merged } as any);
    }
  }
}

Tip:
Merge new values with the existing customData object before calling updateFormField() to avoid overwriting previously stored data.

Read Custom Data from PDF Form Fields

You can access the customData property from any form field at any point in your application flow, such as:

After the document is loaded
During save or submit operations
While performing validation or conditional routing

Standalone
import { Component, AfterViewInit, ViewChild } from '@angular/core';
import {
  ToolbarService,
  MagnificationService,
  NavigationService,
  AnnotationService,
  TextSelectionService,
  TextSearchService,
  FormFieldsService,
  FormDesignerService,
  PdfViewerModule,
} from '@syncfusion/ej2-angular-pdfviewer';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [PdfViewerModule],
  template: `
    <div class="content-wrapper">
      <ejs-pdfviewer 
        #pdfViewer
        [resourceUrl]="resourceUrl"
        [documentPath]="document"
        style="height: 640px; display: block;">
      </ejs-pdfviewer>
    </div>
  `,
  providers: [
    ToolbarService,
    MagnificationService,
    NavigationService,
    AnnotationService,
    TextSelectionService,
    TextSearchService,
    FormFieldsService,
    FormDesignerService,
  ],
})
export class AppComponent implements AfterViewInit {
  @ViewChild('pdfViewer') public pdfviewer: any;
  public document: string =
    'https://cdn.syncfusion.com/content/pdf/form-filling-document.pdf';
  public resourceUrl: string =
    'https://cdn.syncfusion.com/ej2/31.1.23/dist/ej2-pdfviewer-lib';

  ngAfterViewInit(): void {
    this.pdfviewer.documentLoad = () => {
      const fields = this.pdfviewer.retrieveFormFields();
      fields.forEach((f: any) => {
        console.log('Field:', f.name, 'customData:', f.customData);
        // Example: route based on customData
        if (f.customData && f.customData.requiredRole === 'admin') {
          // mark field for special handling
        }
      });
    };
  }
}

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 Syncfusion AI Assistant