Text Input
Text Inputs allow users to enter words, numbers, or characters without styling.
Anatomy
- Label: Title of the Text Input.
- Input Container: Rectangular container that houses the placeholder and input text.
- Placeholder/Input Text: Placeholder text is optional and shows an example of how to format the text for what the input is used for.
Usage Guidance
- Text Inputs can only support words, numbers or characters.
- Standard and Wide Text Inputs does not support images or any text styling.
- To ensure we don’t overwhelm users, there shouldn’t be more than two Wide Text Inputs on a page.
- For all Text Inputs on Web, a user clicking into an input or label that is not disabled will trigger the text cursor to appear, allowing users the ability to type. As the user types in the Text Input, the placeholder text is replaced with the user’s input.
When to Use
- Text Input is typically a form element used to collect user data that includes words, numbers or characters.
When to Use Something Else
- If styling is needed, such as for configuring email messages, you can use a Rich Text Editor instead.
- Use a Text Area when you need to let users enter an amount of text that’s longer than a single line.
- Consider using a Select, Radio or Checkboxes if there are predetermined data that a user should not input themselves.
Examples
Basic Example
Text Input should be used in tandem with Form Field to meet accessibility standards.
Disabled
Set the disabled
prop of the Text Input to prevent users from interacting with it.
Placeholder
Set the placeholder
prop of the Text Input to display a sample of its expected format or value
before a value has been provided.
Ref Forwarding
Text Input supports ref forwarding. It will forward
ref
to its underlying <input type="text">
element.
Grow
Set the grow
prop of the wrapping Form Field to true
to configure the Text Input to expand to
the width of its container.
The grow
prop may also be applied directly to the Text Input if Form Field is not being used.
Label Position
Set the labelPosition
prop of the wrapping Form Field to designate the position of the label
relative to the Text Input. labelPosition
accepts the following values:
FormField.LabelPosition.Top
(Default)FormField.LabelPosition.Left
Required
Set the required
prop of the wrapping Form Field to true
to indicate that the field is required.
Labels for required fields are suffixed by a red asterisk.
Icons
InputGroup
is available to add icons to the TextInput
. Internally, a container div
element is
used with relative position styling on the div
and absolute position styling on the start and end
icons. InputGroup.InnerStart
and InputGroup.InnerEnd
are used to position elements at the start
and end of the input. "start" and "end" are used instead of "left" and "right" to match
CSS Logical Properties
and will be semantically correct in left-to-right and right-to-left languages.
InputGroup.InnerStart
and InputGroup.InnerEnd
subcomponents can handle any child elements, but
are built for icons. The default width is 40px
, which is perfect for icons. If you need to use
something else, be sure to set the width
property of InputGroup.InnerStart
or
InputGroup.InnerEnd
to match the intended width of the element.
Error States
Set the error
prop of the wrapping Form Field to FormField.ErrorType.Alert
or
FormField.ErrorType.Error
to set the Text Input to the Alert or Error state, respectively. You
will also need to set the hintId
and hintText
props on the Form Field to meet accessibility
standards.
The error
prop may be applied directly to the Text Input with a value of
TextInput.ErrorType.Alert
or TextInput.ErrorType.Error
if Form Field is not being used.
Alert
Alert: Please enter a valid email.
Error
Error: Please enter a valid email.
Component API
TextInput
Props
Props extend from input. Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
error |
| The type of error associated with the TextInput (if applicable). | |
width | number | string | The width of the TextInput. | |
theme |
| ||
grow | boolean | True if the component should grow to its container's width. False otherwise. | |
children | React.ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | input |
ref | React.Ref<R = input> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If |
TextInput.ErrorType
Basic type information:
ErrorType
InputGroup
An InputGroup
is a container around a with optional inner start and end
elements. The inner start and end elements are usually icons or icon buttons visually represented
inside the input. The
InputGroup
will add padding to the input so the icons/buttons display
correctly. This component uses React.Children.map
and React.cloneElement
from the
React.Children API. This means all children must be
InputGroup.*
components. Any other direct children will cause issues. You can add different
elements/components inside the and
subcomponents.
<InputGroup><InputGroup.InnerStart as={SystemIcon} pointerEvents="none" icon={searchIcon} /><InputGroup.Input /><InputGroup.InnerEnd><TertiaryButton tabIndex={-1} icon={xIcon} size="small" /></InputGroup.InnerEnd></InputGroup>
Layout Component
InputGroup
supports all props from thelayout component.
Props
Props extend from div. Changing the as
prop will change the element interface.
Props extend from . If a model
is passed, props from InputGroupModelConfig
are ignored.
Name | Type | Description | Default |
---|---|---|---|
cs |
| The
| |
children | ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | div |
ref | React.Ref<R = div> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model |
| Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
InputGroup.InnerStart
A component to show inside and at the start of the input. The input's padding will be
adjusted to not overlap with this element. Use width
(number of pixels only) to adjust the
width offset. The width defaults to 40px which is the correct width for icons or icon
buttons.
Layout Component
InputGroup.InnerStart
supports all props from thelayout component.
Props
Props extend from div. Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
cs |
| The
| |
children | ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | div |
ref | React.Ref<R = div> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model |
| Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
InputGroup.Input
The input to render. By default, this is a . Use the
as
prop to change the
component to be rendered.
Layout Component
InputGroup.Input
supports all props from thelayout component.
Props
Props extend from . Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
cs |
| The
| |
children | ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. |
|
ref | React.Ref<R = > | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model |
| Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
InputGroup.InnerEnd
A component to show inside and at the end of the input. The input's padding will be adjusted
to not overlap with this element. Use width
(number of pixels only) to adjust the width
offset. The width defaults to 40px which is the correct width for icons or icon buttons
within the input.
Layout Component
InputGroup.InnerEnd
supports all props from thelayout component.
Props
Props extend from div. Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
cs |
| The
| |
children | ReactNode | ||
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | div |
ref | React.Ref<R = div> | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model |
| Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
InputGroup.ClearButton
A component that can be added to an input group that will clear the input. It will only render when the input has a value and will fade when a value is entered.
Layout Component
InputGroup.ClearButton
supports all props from thelayout component.
Props
Props extend from . Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
variant | 'inverse' | Variant has an option for | |
isThemeable | boolean | ||
iconPosition | 'start' | 'end' | Button icon positions can either be | 'start' |
fill |
| The fill color of the SystemIcon. This overrides | |
color |
| The color of the SystemIcon. This defines |
|
size |
| There are four button sizes: |
|
styles |
| ||
shouldMirror | boolean | If set to | false |
background |
| The background color of the SystemIcon. |
|
cs |
| The
| |
children | ReactNode | ||
icon |
| The icon of the Button.
Note: not displayed at | |
accent |
| The accent color of the SystemIcon. This overrides | |
accentHover |
| The accent color of the SystemIcon on hover. This overrides | |
backgroundHover |
| The background color of the SystemIcon on hover. |
|
colorHover |
| The hover color of the SystemIcon. This defines |
|
fillHover |
| The fill color of the SystemIcon on hover. This overrides | |
colors |
| Override default colors of a button. The default will depend on the button type | |
fillIcon | boolean | Whether the icon should received filled (colored background layer) or regular styles.
Corresponds to | |
shouldMirrorIcon | boolean | If set to | false |
grow | boolean | True if the component should grow to its container's width. False otherwise. | |
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. |
|
ref | React.Ref<R = > | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
model |
| Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | ( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. |
useClearButton
(
model: ,
elemProps: {},
ref: React.Ref
) => {
role: 'presentation';
tabIndex: unknown {
"kind": "unknown",
"value": "unknown",
"text": "SyntheticNode - PrefixUnaryExpression"
};
icon: ;
size: 'small';
transition: 'opacity 300ms ease';
onMouseDown: (event: ) => void;
onClick: () => void;
style: {
opacity: 0 | 1;
pointerEvents: 'auto' | 'none';
};
}
Model
Specifications
Given | When | Then |
---|---|---|
given the 'Basic' story is rendered |
| |
given the 'Basic' story is rendered |
|
|
given the 'Basic' story is rendered |
|
|
given the 'Alert' story is rendered |
| |
given the 'Alert' story is rendered |
|
|
given the 'Alert' story is rendered |
|
|
given the 'Error' story is rendered |
| |
given the 'Error' story is rendered |
|
|
given the 'Error' story is rendered |
|
|
given the 'Disabled' story is rendered |
| |
given the 'Disabled' story is rendered |
| |
given the 'Placeholder' story is rendered |
| |
given the 'Placeholder' story is rendered |
| |
given the 'Placeholder' story is rendered |
|
Accessibility Guidelines
How Text Inputs Impact the Accessible Experience
Programmatically associating labels and instructions to form inputs is one of the most important foundational practices for building accessible forms.
For Text Input, placeholder values are best used for hints or examples of valid input. Designers should avoid relying on placeholder text for explaining the purpose of the input, as placeholders often don’t provide enough contrast against the text input background. In addition to lower contrast, placeholders disappear once users enter information, impacting users with memory loss, cognitive disabilities, or who are simply distracted.
Keyboard Interaction
Each Text Input must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.
Text Input must support the following keyboard interactions:
Tab
: focus into and out of each text area
Screen Reader Interaction
Text Input must communicate the following to users:
- This component is a text field
- The accessible name (label) describing the purpose of the field
- Text or placeholder values inside the field
- If applicable, whether the field is required, disabled, or invalid
Design Annotations Needed
- No design annotations needed
Implementation Markup Needed
- Text Input must have an
aria-describedby
attribute referencing the uniqueid
value of the error text when an inline alert or error is shown. - Text Input must have a
required
attribute when the field is required for form submission. - [Included in component] A
<label>
element must be added with afor
attribute referencing the uniqueid
value of the associated text area. - [Included in component] An
aria-invalid=”true”
attribute must be set on the Text Input when the field has an error condition. - [Included in component] A
disabled
attribute must be set on the Text Input when the field is disabled.
Content Guidelines
- Labels for Text Inputs are written in title case.
- Refer to the guidelines on Placeholder Text in the Content Style Guide for more tips on how to write placeholder text.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for.
FAQ Section