> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/api-documentation/template-api/template-dynamic-fields-api/formula-field-api.md).

# Formula Field API

Use this page to add a formula field to template XML. A formula field is read-only and calculates its value from other fields.

### Formula field example

```xml
<formula
    name="total_amount"
    placeholder="Total"
    search="true"
    precision="2"
    formatting="true"
    trailingZeros="true"
>SUM({line_total},{doc2::tax})</formula>
```

### Required attributes

* `name` — field name. Use 1 to 128 characters. Do not use `&`, `"`, `<`, or `>`. Keep the value unique within one document.
* `value` — formula expression inside the element body. Use one supported operation per formula.

### Optional attributes

* `placeholder` — placeholder text shown in the template and envelope. Use 0 to 1024 characters. If you omit it, the envelope shows the field name.
* `search` — set to `true` if the field value should be available in envelope search. If you omit it, the default value is `false`.
* `precision` — number of decimal places allowed. If you omit it, the default value is `2`.
* `formatting` — set to `true` to display the value in the user's local number format.
* `trailingZeros` — set to `true` to keep decimal zeros after calculation. Use this attribute with `precision`.

### Supported operations

* `SUM`
* `PRODUCT`
* `SUBTRACT`
* `DIVIDE`
* `COUNTA`
* `MAX`
* `MIN`

### Examples

#### Cross-document formula

```
SUM({field1},{doc2::field2})
```

* `{field1}` — value from the same document.
* `{doc2::field2}` — value of `field2` from document `doc2`.

#### Dynamic table formula

```
SUM({field1})
```

* `{field1}` — field name inside the dynamic table.
* The formula sums values from all rows.

### Related topics

* [Template Dynamic Fields API](/api-documentation/template-api/template-dynamic-fields-api.md)
* [Dynamic Table API](/api-documentation/template-api/template-dynamic-fields-api/dynamic-table-api.md)
* [Number Field API](/api-documentation/template-api/template-dynamic-fields-api/number-field-api.md)
* [Fill Envelope](/api-documentation/envelope/fill-envelope.md)