TextControl Edit

TextControl components let users enter and edit text.

Unfilled and filled TextControl components

Table of contents Table of contents

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

Top ↑

Design guidelines Design guidelines

Usage Usage

When to use TextControls 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.

Top ↑

Anatomy Anatomy

Features of a TextControl component with numbered labels

  1. Label
  2. Input container
  3. Input text

Top ↑

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

Top ↑

Containers 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

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 use unclear visual markers to indicate a text field.

Top ↑

Development guidelines Development guidelines

Top ↑

Usage Usage

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

import { TextControl } from '@wordpress/components';
import { useState } from '@wordpress/element';

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

    return (
            label="Additional CSS Class"
            value={ className }
            onChange={ ( value ) => setClassName( value ) }

Top ↑

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

Top ↑

label label

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

  • Type: String
  • Required: No

Top ↑

hideLabelFromVision hideLabelFromVision

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

  • Type: Boolean
  • Required: No

Top ↑

help help

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

  • Type: String
  • Required: No

Top ↑

type type

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

  • Type: String
  • Required: No
  • Default: “text”

Top ↑

value value

The current value of the input.

  • Type: String | Number
  • Required: Yes

Top ↑

className 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

Top ↑

onChange onChange

A function that receives the value of the input.

  • Type: function
  • Required: Yes

Top ↑

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