Text Input

Anatomy

1. Label: Title of the Text Input.
2. Input Container: Rectangular container that houses the placeholder and input text.
3. 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

Error

Component API

ErrorType

<InputGroup>
  <InputGroup.InnerStart as={SystemIcon} pointerEvents="none" icon={searchIcon} />
  <InputGroup.Input />
  <InputGroup.InnerEnd>
    <TertiaryButton tabIndex={-1} icon={xIcon} size="small" />
  </InputGroup.InnerEnd>
</InputGroup>

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

useInputGroupInput

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

Specifications

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 unique id 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 a for attribute referencing the unique id 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.