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

# Text

> A free-form single-line text input for merchant-defined fields.

The `text` custom element renders a single-line `<input type="text">`. Use it for merchant-defined string data.

## Factory

```typescript theme={null}
overflow.text(options: CustomTextElementOptions): CustomTextElement
```

## Example

```javascript theme={null}
const message = overflow.text({
  name: 'giftMessage',
  label: 'Gift message (optional)',
  placeholder: 'Add a personal note',
  autocomplete: 'off',
});

message.on('onChange', ({ value, complete }) => console.log(value, complete));
message.mount('#gift-message');
```

## Options

| Key                                                 | Type                                        | Default                                                      | Notes                                         |
| --------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
| `elementType`                                       | `'text'`                                    | required                                                     | Discriminant when configured inside Checkout. |
| `name`                                              | `string`                                    | required                                                     | Unique per `Overflow` instance.               |
| `label`                                             | `string`                                    | required                                                     | Renders as `<label>`.                         |
| `placeholder`                                       | `string`                                    | none                                                         |                                               |
| `defaultValue`                                      | `string`                                    | `null`                                                       | Seeds the input on mount.                     |
| `autocomplete`                                      | `string`                                    | none                                                         | HTML autofill token.                          |
| `required`                                          | `boolean`                                   | `false`                                                      | Empty input rejected by built-in check.       |
| `validate`                                          | `(value: string \| null) => string \| null` | none                                                         | Overrides the built-in `required` check.      |
| `disabled`, `readOnly`, `id`, `ariaLabel`, `locale` | shared                                      | see [reference](/payment-elements/elements/custom/reference) |                                               |

## Value

```typescript theme={null}
type CustomTextValue = string | null;
```

`null` while the input is empty.

## Inside Checkout

```javascript theme={null}
overflow.checkout({
  paymentMethods: ['card'],
  customElements: {
    giftMessage: { elementType: 'text', label: 'Gift message (optional)' },
  },
});
```

## See also

* [Custom elements introduction](/payment-elements/elements/custom/introduction)
* [Custom reference](/payment-elements/elements/custom/reference)