Skip to content

custom-data.md

Latest commit

 

History

History
127 lines (101 loc) · 5.84 KB

custom-data.md

File metadata and controls

127 lines (101 loc) · 5.84 KB
Raw
layout post
title Add custom data to form fields in TypeScript Pdf Viewer | Syncfusion
description Learn how to attach, update, and read custom Data on PDF form fields using the Form Designer UI and APIs in the Syncfusion TypeScript PDF Viewer.
platform document-processing
control PDF Viewer
documentation ug

Add custom data to PDF form fields in TypeScript PDF Viewer

The Syncfusion TypeScript PDF Viewer allows attaching application-specific data to form fields using the customData property. This enables associating business identifiers, tags, validation hints, or workflow metadata with form fields.

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:

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()

viewer.documentLoad = () => {
  const meta = { businessId: 'C-1024', tags: ['profile','kiosk'], requiredRole: 'admin' };
  viewer.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, define default customData so newly created fields automatically inherit it. Default custom data can be configured using per-field settings objects such as:

// ...viewer initialization as above...
// Example for textbox defaults
viewer.textFieldSettings = {
  name: 'Textbox',
  customData: { group: 'contact', createdBy: 'designer', requiredRole: 'user' }
} as any;

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

Update or Replace PDF Form Field Custom Data

Modify the customData of an existing form field using updateFormField(). The field can be identified using its object reference or field ID.

// Retrieve existing fields
const fields = viewer.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 });
  viewer.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
viewer.documentLoad = () => {
  const fields = viewer.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

See also