# useWidgetsCreate

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



Returns a function that creates form widgets programmatically and resolves with their snapshots. To let users place widgets by clicking the page instead, switch the interaction tool to `{ type: 'addWidget', widgetProps }` (see [useSetInteractionMode](https://sdk.pdf.net/docs/v1/reference/useSetInteractionMode)).

```ts
const createWidgets = useWidgetsCreate()

const widgets = await createWidgets(props)
const widgets = await createWidgets([props1, props2])
```

Each `props` object requires:

| Prop                        | Meaning                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `pageId`                    | The page to create the widget on.                                                                 |
| `widgetType`                | `'text'`, `'choice'`, `'multiChoice'`, `'checkbox'`, `'radio'`, `'pushButton'`, or `'signature'`. |
| `x`, `y`, `width`, `height` | The widget box in user-space units (the origin is at the bottom-left corner of the page).         |

Everything else is optional and falls back to defaults, including a generated unique `fieldName`. The available properties per kind are listed in [useSetWidgetProps](https://sdk.pdf.net/docs/v1/reference/useSetWidgetProps).

## Behavior [#behavior]

* To make a radio group, create several `radio` widgets with the same `fieldName`.
* The snapshots come in the order of the input. Their ids are session-scoped: don't store them across page reloads.
* The function is asynchronous because the target page may not be loaded yet.
* An unknown `pageId` throws `InvalidInputError`; with no document loaded, the call throws `DocumentNotLoadedError`.

## Example [#example]

```tsx
import { useWidgetsCreate } from '@sdk-pdf/react'

function useAddNameField() {
  const createWidgets = useWidgetsCreate()

  return async (pageId: string) => {
    const [widget] = await createWidgets({
      pageId,
      widgetType: 'text',
      x: 72,
      y: 700,
      width: 180,
      height: 24,
      fieldName: 'customer.name',
    })

    return widget
  }
}
```