Title: TextControl
Published: March 9, 2021
Last modified: September 4, 2026

---

# TextControl

## In this article

 * [Design guidelines](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#design-guidelines)
    - [Usage](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#usage)
    - [Anatomy](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#anatomy)
 * [Development guidelines](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#development-guidelines)
    - [Usage](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#usage-2)
    - [Props](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#props)
 * [Related components](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#related-components)

[ Back to top](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#wp--skip-link--target)

TextControl components let users enter and edit text.

![Unfilled and filled TextControl components](https://i0.wp.com/make.wordpress.org/
design/files/2019/03/TextControl.png?ssl=1)

## 󠀁[Design guidelines](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#design-guidelines)󠁿

### 󠀁[Usage](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#usage)󠁿

#### 󠀁[When to use TextControls](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#when-to-use-textcontrols)󠁿

TextControls are best used for free text entry. If you have a set of predefined 
options you want users to select from, it’s best to use a more constrained component,
such as a SelectControl, RadioControl, CheckboxControl, or RangeControl.

Because TextControls are single-line fields, they are not suitable for collecting
long responses. For those, use a text area instead.

TextControls should:

 * Stand out and indicate that users can input information.
 * Have clearly differentiated states (selected/unselected, active/inactive).
 * Make it easy to understand the requested information and to address any errors.
 * Have visible labels; placeholder text is not an acceptable replacement for a 
   label as it vanishes when users start typing.

### 󠀁[Anatomy](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#anatomy)󠁿

![Features of a TextControl component with numbered labels](https://i0.wp.com/make.
wordpress.org/design/files/2019/03/TextControl-Anatomy.png?ssl=1)

 1. Label
 2. Input container
 3. Input text

#### 󠀁[Label text](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#label-text)󠁿

Label text is used to inform users as to what information is requested for a text
field. Every text field should have a label. Label text should be above the input
field, and always visible.

#### 󠀁[Containers](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#containers)󠁿

Containers improve the discoverability of text fields by creating contrast between
the text field and surrounding content.

![A TextControl with a stroke around the container to clearly indicate the input
area](https://i0.wp.com/make.wordpress.org/design/files/2019/03/TextControl-Do.png?
ssl=1)

**Do**
 A stroke around the container clearly indicates that users can input information.

![A TextControl without a clear visual marker to indicate the input area](https://
i0.wp.com/make.wordpress.org/design/files/2019/03/TextControl-Dont.png?ssl=1)

**Don’t**
 Don’t use unclear visual markers to indicate a text field.

## 󠀁[Development guidelines](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#development-guidelines)󠁿

### 󠀁[Usage](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#usage-2)󠁿

Render a user interface to input the name of an additional css class.

    ```javascript
    import { useState } from 'react';
    import { TextControl } from '@wordpress/components';

    const MyTextControl = () => {
        const [ className, setClassName ] = useState( '' );

        return (
            <TextControl
                label="Additional CSS Class"
                value={ className }
                onChange={ ( value ) => setClassName( value ) }
            />
        );
    };
    ```

### 󠀁[Props](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#props)󠁿

The set of props accepted by the component will be specified below.
 Props not included
in this set will be applied to the input element.

#### 󠀁[label](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#label)󠁿

If this property is added, a label will be generated using label property as the
content.

 * Type: `String`
 * Required: No

#### 󠀁[hideLabelFromVision](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#hidelabelfromvision)󠁿

If true, the label will only be visible to screen readers.

 * Type: `Boolean`
 * Required: No

#### 󠀁[help](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#help)󠁿

If this property is added, a help text will be generated using help property as 
the content.

 * Type: `String`
 * Required: No

#### 󠀁[type](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#type)󠁿

Type of the input element to render. Defaults to “text”.

 * Type: `String`
 * Required: No
 * Default: “text”

#### 󠀁[value](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#value)󠁿

The current value of the input.

 * Type: `String | Number`
 * Required: Yes

#### 󠀁[className](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#classname)󠁿

The class that will be added with “components-base-control” to the classes of the
wrapper div.
 If no className is passed only components-base-control is used.

 * Type: `String`
 * Required: No

#### 󠀁[onChange](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#onchange)󠁿

A function that receives the value of the input.

 * Type: `function`
 * Required: Yes

## 󠀁[Related components](https://developer.wordpress.org/block-editor/reference-guides/components/text-control/?output_format=md#related-components)󠁿

 * To offer users more constrained options for input, use SelectControl, RadioControl,
   CheckboxControl, or RangeControl.

First published

March 9, 2021

Last updated

September 4, 2026

Edit article

[ Improve it on GitHub: TextControl ](https://github.com/WordPress/gutenberg/edit/trunk/packages/components/src/text-control/README.md)

[  Previous: TabPanel](https://developer.wordpress.org/block-editor/reference-guides/components/tab-panel/)

[  Next: TextHighlight](https://developer.wordpress.org/block-editor/reference-guides/components/text-highlight/)