-
Notifications
You must be signed in to change notification settings - Fork 4.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update TextControl design documentation (#14710)
* Update TextControl design documentation * Removing `http://` from anchor links. * Re-arrange Do/Don't image labels To align with the formatting of other READMEs. * Re-edit Do/Don't labels for better consistency.
- Loading branch information
1 parent
445b39e
commit 580fedd
Showing
1 changed file
with
74 additions
and
30 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,72 +1,116 @@ | ||
| # TextControl | ||
| TextControl components let users enter and edit text. | ||
|
|
||
| TextControl is normally used to generate text input fields. But can be used to generate other input types. | ||
|  | ||
|
|
||
| ## Table of contents | ||
|
|
||
| ## Usage | ||
| 1. [Design guidelines](#design-guidelines) | ||
| 2. [Development guidelines](#development-guidelines) | ||
| 3. [Related components](#related-components) | ||
|
|
||
| Render a user interface to input the name of an additional css class. | ||
| ## Design guidelines | ||
|
|
||
| ### Usage | ||
|
|
||
| #### 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 | ||
|
|
||
|  | ||
|
|
||
| 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 | ||
| Containers improve the discoverability of text fields by creating contrast between the text field and surrounding content. | ||
|
|
||
|  | ||
|
|
||
| ```jsx | ||
| import { TextControl } from '@wordpress/components'; | ||
| import { withState } from '@wordpress/compose'; | ||
| **Do** | ||
| A stroke around the container clearly indicates that users can input information. | ||
|
|
||
| const MyTextControl = withState( { | ||
| className: '', | ||
| } )( ( { className, setState } ) => ( | ||
| <TextControl | ||
| label="Additional CSS Class" | ||
| value={ className } | ||
| onChange={ ( className ) => setState( { className } ) } | ||
| /> | ||
| ) ); | ||
| ``` | ||
|  | ||
|
|
||
| ## Props | ||
| **Don’t** | ||
| Don’t use unclear visual markers to indicate a text field. | ||
|
|
||
| ## Development guidelines | ||
|
|
||
| ### Usage | ||
|
|
||
| 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 } ) => ( | ||
| <TextControl | ||
| label="Additional CSS Class" | ||
| value={ className } | ||
| onChange={ ( className ) => setState( { className } ) } | ||
| /> | ||
| ) ); | ||
|
|
||
| ### 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 | ||
|
|
||
| #### label | ||
| If this property is added, a label will be generated using label property as the content. | ||
|
|
||
| - Type: `String` | ||
| - Required: No | ||
|
|
||
| ### help | ||
|
|
||
| #### help | ||
| If this property is added, a help text will be generated using help property as the content. | ||
|
|
||
| - Type: `String|WPElement` | ||
| - Type: `String` | ||
| - Required: No | ||
|
|
||
| ### type | ||
|
|
||
| #### type | ||
| Type of the input element to render. Defaults to "text". | ||
|
|
||
| - Type: `String` | ||
| - Required: No | ||
| - Default: "text" | ||
|
|
||
| ### value | ||
|
|
||
| #### value | ||
| The current value of the input. | ||
|
|
||
| - Type: `Number` | ||
| - Required: Yes | ||
|
|
||
| ### 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 | ||
|
|
||
| ### onChange | ||
|
|
||
| #### onChange | ||
| 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. |