> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt
> Use this file to discover all available pages before exploring further.

# DataFieldAccessor

API reference for the DataFieldAccessor type.

NOTE: **This API is a preview**. Preview APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

Reads and updates the data-field mapping of a single target — obtained from
[DesignEditing.PageHelpers.getDataFieldFor](/docs/apps/api/preview/design-types-page-helpers/).

Updates the data-field mapping and the dataset definition. Supported targets are text (connected
to a field of type `text`) and fills (connected to a field of type `fill`).

When `label` is present:

* If a field with the same label already exists in the dataset definition and its type is
  compatible with the target type, the target is connected to that existing field.
* If a field with the same label exists but has a different type, `set` resolves to
  `{ status: "incompatible_data_field_type" }`.
* If no compatible field exists and the dataset definition has reached the field limit, `set`
  resolves to `{ status: "data_field_limit_exceeded" }`.
* Otherwise a new field is added to the dataset definition with a randomly generated id. The
  field type is inferred from the target type, and the target is connected to it.

When `label` is Unset:

* The data-field mapping is removed from the target.
* The dataset definition is not cleaned up; unused fields are left in place. Unused fields
  continue to count toward the document's data-field limit and may be reused by later calls to
  `set`.

Developer mistakes, such as unsupported targets or invalid fill/parent combinations, throw
`CanvaError({ code: "bad_request" })`.

`getDesignMetadata()` only returns committed data fields. Fields staged during the current
`openDesign` transaction are not visible through `getDesignMetadata()` until `sync()` commits the
changes.

## Methods

<Prop.List>
  <Prop name="get" required type="function" sourceLineNumbers={[1540]}>
    Returns the label of the data field the target is currently connected to, or `undefined` if the
    target is not connected to any data field.

    **Returns**

    `string | undefined`
  </Prop>

  <Prop name="set" required type="function" sourceLineNumbers={[1545]}>
    Stages a change to the target's data-field mapping. The change is committed when the app calls
    `session.sync()`.

    **Parameters**

    <Prop.List>
      <Prop name="opts" required state="preview" type="DataFieldSetOptions" sourceLineNumbers={[1545]}>
        Options for [DataFieldAccessor.set](/docs/apps/api/preview/design-types-data-field-accessor/).

        <PillAccordion defaultExpanded={false} title={<>Properties of <strong>opts</strong></>}>
          <Prop.List>
            <Prop name="label" required type="object" sourceLineNumbers={[1610]}>
              The label of the data field to connect the target to, or Unset to remove the target's
              mapping.

              When a string, the target is connected to a field with this label, creating the field if it
              does not exist. The field type is inferred from the target: text targets use `text` fields and
              fill targets use `fill` fields.

              <Tabs>
                <Tab name="DataFieldLabel" icon={<StateIndicator state="preview" />}>
                  The human-readable label of a data field, for example `"Product name"`. Canva uses the label as
                  the field's identifier within the document's dataset definition.
                </Tab>

                <Tab name="object">
                  *typeof*
                </Tab>
              </Tabs>
            </Prop>
          </Prop.List>
        </PillAccordion>
      </Prop>
    </Prop.List>

    **Returns**

    The result of [DataFieldAccessor.set](/docs/apps/api/preview/design-types-data-field-accessor/). This is a `Promise` that resolves with the following object:

    <Tabs>
      <Tab name="DataFieldAccessorSetResultCompleted" icon={<StateIndicator state="preview" />}>
        Returned by [DataFieldAccessor.set](/docs/apps/api/preview/design-types-data-field-accessor/) when the change was staged successfully.

        <Prop.List>
          <Prop name="status" required type="string" sourceLineNumbers={[1559]}>
            The only valid value is `"completed"`.
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="DataFieldAccessorSetResultError" icon={<StateIndicator state="preview" />}>
        Returned by [DataFieldAccessor.set](/docs/apps/api/preview/design-types-data-field-accessor/) when the change could not be staged.

        * **`data_field_limit_exceeded`** — staging a new field would exceed the dataset field limit.
        * **`incompatible_data_field_type`** — a field with the same label already exists in the dataset
          definition with a type that is incompatible with the target.

        <Prop.List>
          <Prop name="status" required type="string" sourceLineNumbers={[1571]}>
            <Prop.Extras>
              **Available values**:

              * `"data_field_limit_exceeded"`
              * `"incompatible_data_field_type"`
            </Prop.Extras>
          </Prop>
        </Prop.List>
      </Tab>
    </Tabs>
  </Prop>
</Prop.List>