# useSetWidgetProps

Source: https://sdk.pdf.net/docs/v1/reference/useSetWidgetProps



Returns a function that updates properties of widgets by id. To edit the widgets the user selected, read them with [useSelectedBlocks](https://sdk.pdf.net/docs/v1/reference/useSelectedBlocks) and pass their ids.

```ts
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](https://sdk.pdf.net/docs/v1/guides/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`.

## Widget properties [#widget-properties]

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](https://sdk.pdf.net/docs/v1/reference/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](https://sdk.pdf.net/docs/v1/guides/working-with-forms)).

## Example [#example]

```tsx
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:

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