---
title: TextField
description: >-
The `TextField` component captures single-line text input. Use it to collect
short, free-form information in forms and data entry workflows.
The component supports various input configurations including placeholders,
character limits, and validation. It includes built-in support for labels,
helper text, and error states to guide merchants through data entry, ensuring
accurate and efficient information capture across different retail scenarios.
api_version: 2024-10
api_name: pos-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/pos-ui-extensions/2024-10/ui-components/forms/textfield
md: >-
https://shopify.dev/docs/api/pos-ui-extensions/2024-10/ui-components/forms/textfield.md
---
# TextFieldcomponent
The `TextField` component captures single-line text input. Use it to collect short, free-form information in forms and data entry workflows.
The component supports various input configurations including placeholders, character limits, and validation. It includes built-in support for labels, helper text, and error states to guide merchants through data entry, ensuring accurate and efficient information capture across different retail scenarios.
## Properties
Configure the following properties on the `TextField` component.
* label
string
required
The content to use as the field label that describes the text information being requested.
* action
InputAction
A button configuration object displayed under the text field to provide extra functionality.
* disabled
boolean
Controls whether the field can be modified. When `true`, the field is disabled and users cannot edit its value.
* error
string
An error message that indicates a problem to the user. The field is given specific stylistic treatment to communicate issues that must be resolved immediately.
* helpText
string
The label text displayed under the field that provides guidance or instructions to assist users.
* maxLength
number
The maximum number of characters allowed in the text field.
* onBlur
() => void
A callback function executed when focus is removed from the field.
* onChange
(value: string) => void
A callback function executed when the user has finished editing the field, receiving the new text value as a parameter. You should update the `value` property in response to this callback.
* onFocus
() => void
A callback function executed when the field receives focus.
* onInput
(value: string) => void
A callback function executed immediately when the user makes any change in the field. Use this for real-time feedback, such as clearing validation errors as soon as the user begins making corrections. Don't use this to update the `value` property—the `onChange` callback is the appropriate handler for updating the field's value.
* placeholder
string
A short hint that describes the expected value of the field.
* required
boolean
Whether the field needs a value for form submission or validation purposes.
* value
string
The current text value for the field. If omitted, the field will be empty. You should update the `value` property in response to the `onChange` callback.
### InputAction
Defines the configuration object for action buttons displayed below input fields to provide extra functionality.
* disabled
Whether the action button can be pressed.
```ts
boolean
```
* label
The text displayed on the action button.
```ts
string
```
* onPress
A callback function executed when the action button is pressed.
```ts
() => void
```
```ts
export interface InputAction {
/**
* The text displayed on the action button.
*/
label: string;
/**
* A callback function executed when the action button is pressed.
*/
onPress: () => void;
/**
* Whether the action button can be pressed.
*/
disabled?: boolean;
}
```
### Examples
* #### Capture single-line text input
##### Description
Collect short, free-form text using a single-line input field. This example shows a TextField with labels, placeholders, and validation support, ensuring accurate and efficient information capture for forms and data entry workflows.
##### React
```tsx
import React, {useState} from 'react';
import {
TextField,
Screen,
ScrollView,
Navigator,
reactExtension,
Text,
} from '@shopify/ui-extensions-react/point-of-sale';
const SmartGridModal = () => {
const [name, setName] = useState('');
return (
{name ? `Hello ${name}!` : ''}
);
};
export default reactExtension('pos.home.modal.render', () => (
));
```
##### TS
```ts
import {
Navigator,
Screen,
ScrollView,
Text,
TextField,
extension,
} from '@shopify/ui-extensions/point-of-sale';
export default extension('pos.home.modal.render', (root, api) => {
const textField = root.createComponent(TextField, {
label: 'Name',
placeholder: 'Input your name here',
required: true,
value: '',
});
const textBox = root.createComponent(Text);
const onChangeHandler = (newValue: string) => {
textField.updateProps({value: newValue});
const greeting = newValue ? `Hello ${newValue}!` : '';
textBox.replaceChildren(greeting);
};
textField.updateProps({onChange: onChangeHandler});
const scrollView = root.createComponent(ScrollView);
scrollView.append(textField);
scrollView.append(textBox);
const screen = root.createComponent(Screen, {
name: 'TextField',
title: 'Text Field Example',
});
screen.append(scrollView);
const navigator = root.createComponent(Navigator);
navigator.append(screen);
root.append(navigator);
});
```
## Preview
## Best practices
* **Set initial focus appropriately:** When merchants open a new form, set focus on the first text field automatically to streamline data entry and reduce the number of interactions required to begin input.
* **Write clear and concise labels:** Write labels in sentence case and keep them brief. Use consistent terminology for similar fields throughout the app to create a predictable and familiar experience for merchants.
* **Indicate required fields clearly:** When a text field is required for form submission, use the `required` property and display a "Required" indicator. Implement validation logic in your `onChange` callback to check empty values and display errors.
* **Provide helpful guidance with helpText and placeholder:** Use `helpText` for explain content expectations, formatting requirements, or character limits. Use placeholder text to provide examples of the expected content format or structure.
* **Support autocomplete when appropriate:** Provide autocomplete options for fields where merchants commonly enter predictable values, such as addresses, product names, or customer information.
* **Implement character limits appropriately:** Set `maxLength` to prevent excessively long input that might cause display or processing issues. Provide feedback about character limits in the `helpText`, especially when users are approaching the limit.
* **Use action buttons for enhanced functionality:** Use the `action` property to provide helpful actions like "Clear Field," "Generate Code," or "Use Default." This enhances usability by providing quick access to common text operations.
## Limitations
* `TextField` provides single-line text input only—multi-line text entry requires the `TextArea` component.
* The `required` property adds semantic meaning only—it doesn't trigger automatic error display or validation, so you must implement validation logic manually.
* Action buttons are limited to simple press callbacks—complex action workflows require custom implementation or additional components.