> ## 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.

# Text field

> An entered field that stores free text, with optional length limits, character rules, and case and space transforms.

<Info>
  A Text field is a free-text box. A submitter types a value, and you can constrain its length, allowed characters, and patterns, and reshape its case and spaces when the submission is saved.
</Info>

## When to use it

* Campaign names, product names, or any identifier a person types.
* Free-form descriptions that are not drawn from a controlled list.
* Codes or slugs where you want length, character-set, or pattern rules.

<Warning>
  Do not use a Text field when the value should come from a fixed list. Use a [Dropdown](/reference/fields/dropdown) field backed by a picklist instead, so submitters pick rather than type.
</Warning>

## How a value is produced

When a submission is saved, Terminus Hub turns what the submitter typed into the stored value in this order:

1. Takes the typed value, or the `default_value` if the field was left blank.
2. Trims leading and trailing whitespace.
3. Applies `transform_case`.
4. Applies `transform_spaces`.

Validation runs against the trimmed text the submitter typed, before any transforms apply. Length, allowed and disallowed characters, and patterns are all checked at that point. If `unique` is on, uniqueness is checked against the final stored value.

## Settings reference

| Setting                     | Required                                    | Default | Description                                                                                                             |
| --------------------------- | ------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `default_value`             | No                                          | None    | Pre-fills the field for a new submission.                                                                               |
| `min_length`                | No                                          | None    | Minimum character count after trimming, 0 to 1000.                                                                      |
| `max_length`                | No                                          | None    | Maximum character count after trimming, 0 to 1000.                                                                      |
| `allowed_character_types`   | No                                          | None    | Any of `lowercase`, `uppercase`, `numeric`, `space`, `dash`, `underscore`. When set, only these categories are allowed. |
| `allowed_custom_characters` | No                                          | None    | Extra characters allowed on top of `allowed_character_types`, for example `["@", "."]`.                                 |
| `disallowed_characters`     | No                                          | None    | Characters that are always rejected. Takes precedence over the allow settings.                                          |
| `patterns`                  | No                                          | None    | A list of `{ type, value, message }` rules. `type` is one of `contains`, `starts`, `ends`, `excludes`, `regex`.         |
| `transform_case`            | No                                          | `none`  | `none`, `lowercase`, or `uppercase`. Applied on save.                                                                   |
| `transform_spaces`          | No                                          | `none`  | `none`, `remove`, `replace_dash`, `replace_underscore`, or `replace_custom`. Applied on save.                           |
| `custom_replacement`        | When `transform_spaces` is `replace_custom` | None    | The text that replaces each space. Up to 5 characters.                                                                  |
| `unique`                    | No                                          | `false` | When true, the stored value must be unique across records.                                                              |

The `required` flag lives on the field itself, not inside `settings`.

## Example

A `campaign_name` field in a Campaign URL Builder model:

```yaml theme={null}
name: campaign_name
type: text
required: true
settings:
  unique: true
  transform_case: lowercase
  transform_spaces: replace_underscore
```

A submitter types `Black Friday 2026`. On save, Terminus Hub trims it, lowercases it to `black friday 2026`, then replaces spaces with underscores. The stored value is `black_friday_2026`. That transformed value is what downstream computed fields, such as `utm_campaign` or a `short_url`, build on.

## Gotchas

* **Transforms apply on save, not as you type.** The submitter still sees their original input in the form. The transformed result is what gets stored.
* **Validation sees the text before transforms.** A pattern that requires an underscore will not match a value the submitter typed with a space, even when `transform_spaces: replace_underscore` would later produce one.
* **`patterns` are typed, not raw regex.** Only the `regex` type treats `value` as a regular expression. `contains`, `starts`, `ends`, and `excludes` are literal string matches. Every pattern needs a `message`.
* **`replace_custom` needs `custom_replacement`.** You cannot save the field with `transform_spaces: replace_custom` and no `custom_replacement`.

## Related

* [Dropdown field](/reference/fields/dropdown): when the value should come from a fixed list.
* [Concatenation field](/reference/fields/concatenation): when the value should be built from other fields, including Text fields.
* [Fields](/reference/fields)