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

# Auto-fill field

> A computed field that derives its value from other fields, either copying one field with transforms or evaluating an expression with filters and conditions.

<Info>
  An Auto-fill field derives its value from other fields on the same row. In its simple form it copies one field and reshapes it (case, spaces, a fallback). In its expression form it combines any number of fields with literal text, transforms, and if/else logic. Like every computed field, submitters see the result but never type into it.
</Info>

## When to use it

* A slug-safe copy of another field: Campaign Name, but lowercase and dash-separated.
* A value that needs a fallback when its source is empty.
* A code that varies by condition: one prefix when the platform is DV360, another otherwise.

<Warning>
  If all you need is other fields joined in a fixed shape (`goal-country-name`), use a [Concatenation field](/reference/fields/concatenation): it is simpler and supports uniqueness. If the value never changes at all, use a [Constant field](/reference/fields/constant). Reach for Auto-fill when you need to transform or choose values, not just join them.
</Warning>

## The two modes

The editor's **Auto-fill settings** section has a two-way switch:

* **Copy a field** takes one source field and applies optional transforms.
* **Expression** evaluates a template that can reference many fields.

Switching modes discards the other mode's configuration entirely, so settle the shape before you configure the details.

## Copy a field (simple mode)

| Control            | Setting              | What it does                                                                                                  |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------- |
| Source field       | `source_field_id`    | The field to copy the value from.                                                                             |
| Letter case        | `transform_case`     | `none`, `lowercase`, or `uppercase`.                                                                          |
| Spaces             | `transform_spaces`   | Keep, remove, replace with dash or underscore, or replace with a custom character.                            |
| Custom replacement | `custom_replacement` | The replacement text (up to 5 characters). Only shown, and required, when Spaces is set to the custom option. |
| Default value      | `default_value`      | Used when the source field is empty.                                                                          |

The value is computed as: read the source, substitute the default if the source is blank, then apply the case and space transforms. The default is transformed too: a default of `Not Set` with uppercase on yields `NOT SET`.

## Expression mode

An expression mixes literal text with field references written as `{{ handle }}`, using the field's [handle](/reference/fields). The syntax is the Liquid template language, restricted to a safe subset.

The editor offers two views, switched with the **Visual** and **Advanced** buttons:

* **Visual** shows field references as pills carrying the field's display name. Type `/` or click **Insert field** to add a field, and click a pill to attach transforms from a menu: Lowercase, Uppercase, Capitalize, Trim spaces, Remove spaces, Spaces to dashes, Spaces to underscores, Truncate, Fallback if empty, Replace, Add prefix, Add suffix.
* **Advanced** is the raw expression text. Everything Visual can build, plus conditionals (`{% if %}`, `{% elsif %}`, `{% else %}`, `{% case %}`) and the full filter set. An expression that uses features Visual cannot show (any conditional, for example) stays in Advanced, and the Visual button is disabled.

The allowed filters are: `upcase`, `downcase`, `capitalize`, `strip`, `lstrip`, `rstrip`, `replace`, `remove`, `append`, `prepend`, `truncate`, `slice`, `default`, and `date`. Loops and includes are not available, and any other filter is rejected. An expression can be up to 2,000 characters and its rendered output up to 5,000.

Below the editor, **Preview with sample values** gives you one input per referenced field and renders the result live, through the same engine the submission pipeline uses, so what you see in the preview is what records will produce.

## Which fields can be referenced

Both modes accept single-value fields: Text, URL, Date, single-select Dropdown, Constant, Auto number, Random, Terminus ID, and other Auto-fill fields. Compound fields (Concatenation, Tagged URL, Short URL, QR code) and multi-select dropdowns cannot be sources; build from the same primitives instead, or reference the Auto-fill from the compound field. Circular references are rejected when the model is validated or published.

## Settings reference

Simple mode:

| Setting              | Required                        | Default | Description                                                                  |
| -------------------- | ------------------------------- | ------- | ---------------------------------------------------------------------------- |
| `mode`               | Yes                             | None    | The literal string `simple`.                                                 |
| `source_field_id`    | Yes                             | None    | The field to copy from.                                                      |
| `transform_case`     | No                              | `none`  | `none`, `lowercase`, or `uppercase`.                                         |
| `transform_spaces`   | No                              | `none`  | `none`, `remove`, `replace_dash`, `replace_underscore`, or `replace_custom`. |
| `custom_replacement` | When spaces is `replace_custom` | None    | Up to 5 characters.                                                          |
| `default_value`      | No                              | None    | Substituted when the source is empty, before transforms.                     |

Expression mode:

| Setting                | Required       | Default | Description                                                                              |
| ---------------------- | -------------- | ------- | ---------------------------------------------------------------------------------------- |
| `mode`                 | Yes            | None    | The literal string `expression`.                                                         |
| `expression`           | Yes            | None    | The template. At least one character.                                                    |
| `dependency_field_ids` | Never set this | Derived | Terminus Hub derives it from the expression on every save; anything you send is ignored. |

The two modes cannot be mixed in one settings object. Auto-fill is a computed field, so `required` is locked on and submitters cannot edit the value. A prefix and suffix are allowed and are wrapped around the computed result. There is no `unique` setting; if the value must be unique, use a [Concatenation field](/reference/fields/concatenation) instead.

## A worked example

A campaign code that shortens known platforms and slugs the campaign name, built in Advanced mode from a `platform` dropdown, a `region` dropdown, a `campaign_name` text field, and a `sequence` auto number:

```yaml theme={null}
name: Campaign Code
type: autofill
settings:
  mode: expression
  expression: >-
    {% if platform == 'dv360' %}dbm{% elsif platform == 'ttd' %}ttd{% else %}{{ platform }}{% endif %}-{{ region | downcase }}-{{ campaign_name | downcase | replace: ' ', '-' | truncate: 24 }}-{{ sequence }}
```

With `platform = dv360`, `region = EMEA`, `campaign_name = Black Friday Sale`, and `sequence = 00042`, the field computes:

```text theme={null}
dbm-emea-black-friday-sale-00042
```

The simpler variant without the conditional, `{{ region | downcase }}-{{ campaign_name | downcase | replace: ' ', '-' }}`, is fully editable in Visual mode as two pills with a `-` between them.

## Gotchas

* **Switching modes wipes the other mode's settings.** Moving from Copy a field to Expression discards the source and transforms; moving back discards the expression.
* **Expressions reference fields by handle, so renaming a handle breaks them.** Publish is blocked with "Autofill expression references unknown field" until every affected expression is updated.
* **A broken expression saves but does not publish.** The field editor accepts any text; invalid syntax or a disallowed filter is caught when you validate or publish the model, and a failure at submission time marks the cell "Autofill expression failed to evaluate" and blocks approval.
* **An empty result blocks approval.** Auto-fill is always required, so an expression that legitimately renders nothing makes the row invalid. Give it a fallback: the **Fallback if empty** transform, or simple mode's default value.
* **Truncate counts the ellipsis.** The Truncate transform is Liquid's `truncate`: the three trailing dots it appends count toward the length. For a plain "first N characters," use `slice` in Advanced mode.
* **A referenced field must be in the same taxonomy to have a value.** The picker offers fields from the whole governance model and marks ones missing from the current taxonomy; referencing one of those yields an empty value on this taxonomy's records.
* **Values are recomputed on every save.** Editing the expression changes what newly saved rows produce. Approved records keep the value they were approved with.

## Related

* [Concatenation field](/reference/fields/concatenation): fixed-shape joining, with uniqueness.
* [Constant field](/reference/fields/constant): a fixed literal value.
* [Text field](/reference/fields/text): the same case and space transforms, applied to typed input.
* [Fields](/reference/fields)