Programmatic Support for Form Designer in Blazor PDF Viewer
The Blazor SfPdfViewer component provides programmatic control over PDF form fields, enabling creation, update, and management entirely through code for automated and reliable form workflows.
NOTE
Programmatic operations do not require enabling the Form Designer UI. Ensure a document is loaded and an instance reference (for example, SfPdfViewer2 via @ref) is available before invoking API methods.
Adding Form Fields Programmatically
The Blazor SfPdfViewer offers a way to add form fields programmatically using the AddFormFieldsAsync method. This method accepts a list of FormFieldInfo objects, where each object represents a form field (for example, ButtonField, TextBoxField, PasswordField, CheckBoxField, RadioButtonField, DropDownField, ListBoxField, SignatureField) with specific properties and Bound coordinates.
The example below demonstrates how to add form fields in the SfPdfViewer2 component:
@page "/"
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
<PdfViewerEvents DocumentLoaded="@AddFormFields"></PdfViewerEvents>
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Path to the PDF document
private string DocumentPath = "wwwroot/data/formDesigner_Empty.pdf";
// Method triggered when the document is loaded
private async Task AddFormFields()
{
// Define various form fields with their properties and positions
List<FormFieldInfo> formFields = new List<FormFieldInfo>
{
new ButtonField { Name = "Button Field", Bounds = new Bound { X = 278, Y = 157, Width = 150, Height = 40 } },
new TextBoxField { Name = "TextBox Field", Bounds = new Bound { X = 278, Y = 247, Width = 200, Height = 24 } },
new PasswordField { Name = "Password Field", Bounds = new Bound { X = 278, Y = 323, Width = 200, Height = 24 } },
new CheckBoxField { Name = "CheckBox Field1", IsChecked = false, Bounds = new Bound { X = 278, Y = 398, Width = 20, Height = 20 } },
new CheckBoxField { Name = "CheckBox Field2", IsChecked = false, Bounds = new Bound { X = 386, Y = 398, Width = 20, Height = 20 } },
new RadioButtonField { Name = "RadioButton", Value = "Value1", IsSelected = false, Bounds = new Bound { X = 278, Y = 470, Width = 20, Height = 20 } },
new RadioButtonField { Name = "RadioButton", Value = "Value2", IsSelected = false, Bounds = new Bound { X = 386, Y = 470, Width = 20, Height = 20 } },
new DropDownField { Name = "DropDown Field", Bounds = new Bound { X = 278, Y = 536, Width = 200, Height = 24 } },
new ListBoxField { Name = "ListBox Field", Bounds = new Bound { X = 278, Y = 593, Width = 198, Height = 66 } },
new SignatureField { Name = "Signature Field", Bounds = new Bound { X = 278, Y = 686, Width = 200, Height = 63 } }
};
// Add form fields asynchronously to the PDF Viewer
await viewer.AddFormFieldsAsync(formFields);
}
}The following image illustrates the programmatic addition of form fields in Blazor SfPdfViewer:
NOTE
Form fields can also be added interactively using the Form Designer UI for an intuitive, point-and-click experience.
Interactively Add Form Fields
Form Field Settings
The Blazor SfPdfViewer provides FormFieldSettings to configure form field appearance, including borders, background, text styles, and related properties.
The example below demonstrates configuring thickness. Additional options include background color, border color, text color, font family, font size, and font style.
@page "/"
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
<!-- Form field settings with specified thickness -->
<FormFieldSettings Thickness="@thickness"></FormFieldSettings>
<!-- Event triggered when the document is loaded -->
<PdfViewerEvents DocumentLoaded="@AddFormFields"></PdfViewerEvents>
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Default thickness value for form fields
private double thickness { get; set; } = 4;
// Path to the PDF document to be loaded in the viewer
private string DocumentPath = "wwwroot/data/formDesigner_Empty.pdf";
// Method triggered when the document is loaded
private async Task AddFormFields()
{
// Define a new ListBox form field with specified name and position
ListBoxField listBox = new ListBoxField
{
Name = "ListBox Field",
Bounds = new Bound { X = 278, Y = 593, Width = 198, Height = 66 }
};
// Add the form field asynchronously to the PDF Viewer
await viewer.AddFormFieldsAsync(new List<FormFieldInfo> { listBox });
}
}The following image illustrates the listbox field thickness customization in Blazor SfPdfViewer:
Activating and Deactivating Form Field Mode
The SetFormDrawingModeAsync method defines the type of form field that can be drawn interactively in the viewer. This controls the UI drawing behavior and is independent of programmatic creation via AddFormFieldsAsync.
- Setting Form Field Mode: Specify a FormFieldType to allow adding a specific form field.
- Clearing Form Field Mode: Reset the form field selection by calling SetFormDrawingModeAsync() without parameters.
Example
Below is an example demonstrating how to set and clear the form field drawing mode:
@page "/"
@using Syncfusion.Blazor.Buttons
<!-- Buttons to set and clear the form field drawing mode -->
<SfButton @onclick="SetFormDrawingMode">Set Form Field Type</SfButton>
<SfButton @onclick="ClearFormDrawingMode">Clear Form Field Type</SfButton>
<!-- PDF Viewer component -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Path to the PDF document to be loaded in the viewer
private string DocumentPath = "wwwroot/data/formDesigner_Empty.pdf";
// Method to enable form field drawing mode with a specific field type
async Task SetFormDrawingMode()
{
// Sets the form field drawing mode to DropDown, allowing users to add dropdown fields
await viewer.SetFormDrawingModeAsync(FormFieldType.DropDown);
}
// Method to disable form field drawing mode
async Task ClearFormDrawingMode()
{
// Clears the form field drawing mode, preventing further form field additions
await viewer.SetFormDrawingModeAsync();
}
}The following image illustrates setting and clearing the form field mode in Blazor SfPdfViewer:
Update Form Fields
Form fields can be modified dynamically by retrieving them with GetFormFieldsAsync() and applying changes using UpdateFormFieldsAsync(). Use null/empty checks and batch updates to efficiently apply multiple changes.
Appearance Properties
Controls the visual aspects of form fields, including background color, border color, text color, thickness, maxLength, visibility, font size, font family, font style, and text alignment. These properties customize the visual presentation of fields.
@page "/"
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
<!-- Event triggered when the document is loaded -->
<PdfViewerEvents DocumentLoaded="@UpdateFormField"></PdfViewerEvents>
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Path to the PDF document to be loaded in the viewer
private string DocumentPath = "wwwroot/data/formDesigner_Document.pdf";
// Method triggered when the document is loaded
private async Task UpdateFormField()
{
// Retrieve the list of added form fields from the PDF Viewer
List<FormFieldInfo> formFields = await viewer.GetFormFieldsAsync();
// Access the first form field in the list (assuming it is a button field)
FormFieldInfo buttonField = formFields[0];
// Modify the appearance properties of the form field
buttonField.BackgroundColor = "#008000";
buttonField.BorderColor = "#FFFF00";
buttonField.Thickness = 2;
// Update the form field in the PDF Viewer with the new properties
await viewer.UpdateFormFieldsAsync(new List<FormFieldInfo> { buttonField });
}
}The following image illustrates updating the appearance of a button form field in Blazor SfPdfViewer:
Identification & Metadata Properties
Use name (identifier) and value (display/value data) on dropdown [ListItem] entries to define item metadata. These properties help organize options and manage related form fields effectively.
@page "/"
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
<PdfViewerEvents DocumentLoaded="@UpdateFormField"></PdfViewerEvents>
</SfPdfViewer2>
@code {
private SfPdfViewer2 viewer;
private string DocumentPath = "wwwroot/data/formDesigner_Document.pdf";
private async Task UpdateFormField()
{
// Retrieve the list of added form fields
List<FormFieldInfo> formFields = await viewer.GetFormFieldsAsync();
foreach (FormFieldInfo field in formFields)
{
if (field is DropDownField dropDown)
{
dropDown.Items = new List<ListItem> {
new ListItem { Name = "option 1", Value = "Option 1" },
new ListItem { Name = "option 2", Value = "Option 2" },
new ListItem { Name = "option 3", Value = "Option 3" }
};
// Update form fields in the viewer with new properties
await viewer.UpdateFormFieldsAsync(new List<FormFieldInfo> { dropDown });
}
}
}
}The following image illustrates updating the metadata of a dropdown field in Blazor SfPdfViewer:
Grouping and Synchronizing Form Fields Properties
When multiple fields share the same name, changes apply to all linked fields. Updates to Value, Required, Readonly, Multiline, and Tooltip reflect instantly. This ensures consistency across the document.
@page "/"
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
<PdfViewerEvents DocumentLoaded="@UpdateFormField"></PdfViewerEvents>
</SfPdfViewer2>
@code {
private SfPdfViewer2 viewer;
private string DocumentPath = "wwwroot/data/formDesigner_Document.pdf";
private async Task UpdateFormField()
{
// Retrieve the list of added form fields
List<FormFieldInfo> formFields = await viewer.GetFormFieldsAsync();
FormFieldInfo radioButton = formFields[6];
radioButton.IsReadOnly = true;
radioButton.IsRequired = true;
await viewer.UpdateFormFieldsAsync(new List<FormFieldInfo> { radioButton });
}
}The following image illustrates updating linked properties of a radio button form field in Blazor SfPdfViewer:
NOTE
Users can also update form fields through the UI in SfPdfViewer for an intuitive, interactive experience.
Interactively Update Form Fields
Delete Form Fields
The DeleteFormFieldsAsync() method enables the removal of form fields from the document, allowing users to manage and modify form structures efficiently.
Delete All Form Fields
Removes all form fields from the document using DeleteFormFieldsAsync() , clearing all interactive elements at once.
@page "/"
@using Syncfusion.Blazor.Buttons
<!-- Button to delete all form fields -->
<SfButton onclick="@DeleteAllFormFields">Delete All Form Fields</SfButton>
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Path to the PDF document
private string DocumentPath = "wwwroot/data/formDesigner_Document.pdf";
private async Task DeleteAllFormFields()
{
// Deletes all form fields from the PDF Viewer.
await viewer.DeleteFormFieldsAsync(true);
}
}The following image illustrates deleting all form fields in Blazor SfPdfViewer:
Delete Selected Form Fields
Deletes only the currently selected form field using DeleteFormFieldsAsync(), enabling users to modify the document while keeping the rest of the form structure intact.
@page "/"
@using Syncfusion.Blazor.Buttons
<!-- Button to delete the selected form fields -->
<SfButton onclick="@DeleteSelectedFormField">Delete Selected Form Field</SfButton>
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Path to the PDF document
private string DocumentPath = "wwwroot/data/formDesigner_Document.pdf";
private async Task DeleteSelectedFormField()
{
// Delete selected form field from the PDF Viewer.
await viewer.DeleteFormFieldsAsync(false);
}
}The following image illustrates deleting a selected password field in Blazor SfPdfViewer:
Delete Form Fields by IDs
Removes specific form fields using DeleteFormFieldsAsync() based on their unique identifiers, allowing precise control over which fields are deleted without affecting others. The example below deletes a single field by ID; pass multiple IDs to delete several fields at once.
@page "/"
@using Syncfusion.Blazor.Buttons
<!-- Delete form fields by ID -->
<SfButton @onclick="DeleteFormFields">Delete Form Field By ID</SfButton>
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Path to the PDF document that will be loaded into the viewer
private string DocumentPath = "wwwroot/data/formDesigner_Document.pdf";
// Method to delete form fields based on their ID
private async Task DeleteFormFields()
{
List<FormFieldInfo> formFields = await viewer.GetFormFieldsAsync();
await viewer.DeleteFormFieldsAsync(new List<string> {formFields[0].Id}); // Delete form fields by ID
}
}The following image illustrates deleting form fields by their IDs in Blazor SfPdfViewer:
NOTE
Users can also delete form fields through the UI in SfPdfViewer for an intuitive, interactive experience.
Interactively Delete Form Fields
Select Form Field
Form fields can be programmatically selected using the SelectFormFieldAsync method. Selection is supported either by unique ID or by passing the form field object reference.
Select Form Field by ID
The following example demonstrates selecting a form field by passing the form field object reference to SelectFormFieldAsync. To select by unique ID instead, use the string overload of SelectFormFieldAsync.
@page "/"
@using Syncfusion.Blazor.Buttons
<!-- Button to select a form field by its ID -->
<SfButton @onclick="SelectFormFieldByID">Select Form Field By ID</SfButton>
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Path to the PDF document that will be loaded in the viewer
private string DocumentPath = "wwwroot/data/formDesigner_Document.pdf";
// Method to select a form field by ID
private async Task SelectFormFieldByID()
{
// Retrieve all form fields currently present in the PDF
List<FormFieldInfo> formFields = await viewer.GetFormFieldsAsync();
// Select the form field asynchronously using its ID
await viewer.SelectFormFieldAsync(formFields[0]);
}
}The following image illustrates selecting a button field in Blazor SfPdfViewer:
Select Form Field by Object Reference
Optionally, retrieve all available form fields using GetFormFieldsAsync, and then select a specific field by passing its object reference to SelectFormFieldAsync.
@page "/"
@using Syncfusion.Blazor.Buttons
<!-- Button to trigger form field selection -->
<SfButton @onclick="SelectFormField">Select Form Field</SfButton>
<!-- PDF Viewer component with reference binding and document loading -->
<SfPdfViewer2 @ref="@viewer" Height="100%" Width="100%" DocumentPath="@DocumentPath">
</SfPdfViewer2>
@code {
// Reference to the PDF Viewer instance
private SfPdfViewer2 viewer;
// Path to the PDF document that will be loaded in the viewer
private string DocumentPath = "wwwroot/data/formDesigner_Document.pdf";
// Method to select the first available form field in the document
private async Task SelectFormField()
{
// Retrieve all form fields present in the PDF
List<FormFieldInfo> formFields = await viewer.GetFormFieldsAsync();
// Select the first form field from the list
FormFieldInfo formField = formFields[3];
await viewer.SelectFormFieldAsync(formField);
}
}The following image shows selecting a checkbox field in the Blazor PDF Viewer (SfPdfViewer):
NOTE
Enable the form field interaction mode before selecting a field.
For details, see Interaction mode.