---
title: Text field
description: Display a string as plain text or a common contact value.
---

A text field declares a string value. Use a format to say what the string is:
an email address, a URL, a phone number, or Markdown. The renderer controls the
final presentation and interaction.

## API

```ts
fields.text<Name extends string>(
  name: Name,
  options?: TextFieldOptions
): TextFieldBuilder<Name>
```

| Option         | Input                                  | Result                              |
| -------------- | -------------------------------------- | ----------------------------------- |
| `label`        | `string`                               | Sets the text shown for the field.  |
| `description`  | `string`                               | Adds supporting text for the label. |
| `format`       | `email`, `url`, `phone`, or `markdown` | Says what the string is.            |
| `inputVariant` | `input` or `textarea`                  | Refines the form control.           |

`configure(options)` returns a configured clone. `clone()` returns an
independent copy with the same options.

If you do not provide a label, the protocol uses an empty string. It leaves other
unset options out of the field node.

## Basic text field

Pass the record key to `fields.text` and add the label shown by the renderer.

<BacklitExample path="fields/text/basic" view="detail" />

## Description

A description supplies supporting text for the field label.

<BacklitExample path="fields/text/description" view="detail" />

## Formats

Text supports four formats. A format says what the string is. The value on the
wire is the string in every case.

| Format     | Use                             | Form control                           |
| ---------- | ------------------------------- | -------------------------------------- |
| `email`    | An email address.               | A single line with the email keyboard. |
| `url`      | An absolute or application URL. | A single line with the URL keyboard.   |
| `phone`    | A telephone number.             | A single line with the phone keyboard. |
| `markdown` | Markdown source.                | A textarea beside a rendered preview.  |

A `markdown` value renders in the browser. The built-in renderer does not
render raw HTML inside the source. A host replaces the renderer through the
`blocks.markdown` registry entry to use its own pipeline and components.

The editor preview uses the `blocks['markdown-preview']` registry entry. When you do
not set it, the preview uses `blocks.markdown`.
Set it when the preview must show more than the body: for example, an email
with its subject and template around the source. The preview renders inside
the form, and the `useFormValues` hook from `@backlit/ui` returns the current
values of the other fields.

```tsx
<BacklitApp {...appProps} blocks={{ 'markdown-preview': NewsletterPreview }}>
  {children}
</BacklitApp>
```

`NewsletterPreview` receives a `source` string. Extensions can supply the same
registry entry. The host's entry takes precedence over extension entries.

<BacklitExample path="fields/text/formats" view="detail" />

## Input variants

Input variants affect forms. The format picks the control. An input variant
refines it: `input` for one line, `textarea` for multiple lines. A `textarea` on
a `markdown` field edits the source with no preview. Input variants do not
change the read-only value in a datalist or table.

<BacklitExample path="fields/text/input_variants" view="detail" />

## Clone

Use `configure` to reuse a declaration with different options. It clones the
field first, so the original field does not change.

<BacklitExample path="fields/text/clone" view="detail" />

## All options

You can use a label, description, format, and input variant on the same text field.

<BacklitExample path="fields/text/all_options" view="detail" />