useSetWidgetProps

Returns a function that updates properties of widgets by id. To edit the widgets the user selected, read them with useSelectedBlocks and pass their ids.

const setWidgetProps = useSetWidgetProps()

await setWidgetProps(widgetIds, props, options?)

Properties a widget's kind doesn't support are ignored, so one call can span widgets of different kinds; every supplied widget gets the properties it supports.
The properties are applied immediately, when the function is called. The returned promise resolves once the widgets show their new state: renaming a field into one whose value is stored on a page not loaded yet waits for that value to load.
Pass { excludeFromHistory: true } as options for changes that must not be undoable, such as locking a submitted form (see Working with forms).
Every id must identify an existing widget, or the call throws InvalidInputError; an empty fieldName throws it too. With no document loaded, the call throws DocumentNotLoadedError.

Properties shared by every widget kind:

Prop	Type	Meaning
`x`, `y`, `width`, `height`	`number`	The widget box in user-space units.
`fieldName`	`string`	The field the widget belongs to; same-named widgets share the value. Names aren't checked for conflicts: a widget renamed to an existing field name joins that field and shares its value.
`isReadOnly`	`boolean`	Restricts changing the field value (form filling), not authoring the widget itself.
`isRequired`	`boolean`	The PDF Required field flag. It is saved with the document; the SDK doesn't enforce it.
`borderColor`	`ColorString`	The border color; opacity is carried in the alpha channel.
`borderWidth`	`number`	The border width in user-space units.
`fillColor`	`ColorString`	The background color. Translucent values are saved as either opaque or transparent.

Kinds that draw text or marks (all but signature) also carry:

Prop	Type	Meaning
`fontSize`	`number`	In user-space units. `0` means automatic: the largest size that fits.
`textColor`	`ColorString`	The text or check mark color. Translucent values are saved as either opaque or transparent.

Kinds laying out variable text (text, choice, multiChoice) also carry horizontalAlign: how the lines align within the widget.

Per kind:

Kind	Props
`text`	`isMultiline`; `isMonospaced` (fixed character width, requires `maxLength` and single-line); `maxLength` (`null` means no limit); `format` (see FormatType, `null` means plain text). A multiline field ignores its `format`, so clear the format when making a field multiline.
`checkbox`	`checkedValue` (the value stored when checked); `checkedStateName`; `checkMark` (a single ZapfDingbats character drawn when checked).
`radio`	The `checkbox` props, plus `canToggleToOff` (clicking the checked option unchecks it) and `isInUnison` (options sharing a `checkedValue` check together).
`choice`	`options` (the selectable options: stored `value` and displayed `label`); `isCombo` (dropdown instead of a list box); `allowsCustomValue` (a combobox accepts arbitrary typed text).
`multiChoice`	`options` and `isCombo`, as in `choice`.
`pushButton`	`caption`: the button label text.
`signature`	No own editable props. Its `isCryptoSigned` is read-only: it mirrors the loaded document, and the SDK never signs.

id, pageId, type, subtype, and widgetType can't be changed: ids are immutable, and changing the kind means replacing the widget (see Working with forms).

Example

import { Block, TextWidget, useSelectedBlocks, useSetWidgetProps } from '@sdk-pdf/react'

function MultilineToggle() {
  const selectedBlocks = useSelectedBlocks()
  const setWidgetProps = useSetWidgetProps()

  const textWidgets = selectedBlocks.filter(isTextWidget)
  if (textWidgets.length === 0) return null

  const isMultiline = textWidgets.every((widget) => widget.isMultiline)
  const widgetIds = textWidgets.map((widget) => widget.id)

  return (
    <label>
      <input
        type="checkbox"
        checked={isMultiline}
        // A multiline field ignores the format, so making the fields multiline clears it.
        onChange={(event) =>
          void setWidgetProps(
            widgetIds,
            event.currentTarget.checked
              ? { isMultiline: true, format: null }
              : { isMultiline: false }
          )
        }
      />
      Multiline
    </label>
  )
}

function isTextWidget(block: Block): block is TextWidget {
  return (
    block.type === 'annotation' &&
    block.subtype === 'Widget' &&
    block.widgetType === 'text'
  )
}

One call can also span mixed kinds, each widget taking the props it supports:

await setWidgetProps(widgetIds, { isReadOnly: true, fillColor: 'rgba(245,245,245,1)' })

useSetWidgetProps

Widget properties

Example

On this page