Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


TextControl components let users enter and edit text.

Unfilled and filled TextControl components

Table of contents

  1. Design guidelines
  2. Development guidelines
  3. Related components

Design guidelines


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.


Features of a TextControl component with numbered labels

  1. Label
  2. Input container
  3. Input text

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

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

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

Development guidelines


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

import { TextControl } from '@wordpress/components';
import { withState } from '@wordpress/compose';

const MyTextControl = withState( {
    className: '',
} )( ( { className, setState } ) => ( 
        label="Additional CSS Class"
        value={ className }
        onChange={ ( className ) => setState( { className } ) }
) );


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.


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

  • Type: String
  • Required: No


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

  • Type: Boolean
  • Required: No


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

  • Type: String
  • Required: No


Type of the input element to render. Defaults to "text".

  • Type: String
  • Required: No
  • Default: "text"


The current value of the input.

  • Type: String | Number
  • Required: Yes


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


A function that receives the value of the input.

  • Type: function
  • Required: Yes

Related components

  • To offer users more constrained options for input, use SelectControl, RadioControl, CheckboxControl, or RangeControl.
You can’t perform that action at this time.