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 ensure proper label association and screen reader support.

import React from 'react';

import {FormField} from '@workday/canvas-kit-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField>
      <FormField.Label>Email</FormField.Label>
      <FormField.Field>
        <FormField.Input as={TextInput} onChange={handleChange} value={value} />
      </FormField.Field>
    </FormField>
  );
};

Disabled

Set the disabled prop of the Text Input to prevent users from interacting with it.

import React from 'react';

import {FormField} from '@workday/canvas-kit-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField>
      <FormField.Label>Email</FormField.Label>
      <FormField.Field>
        <FormField.Input as={TextInput} disabled onChange={handleChange} value={value} />
      </FormField.Field>
    </FormField>
  );
};

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.

import React from 'react';

import {FormField} from '@workday/canvas-kit-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField>
      <FormField.Label>Email</FormField.Label>
      <FormField.Field>
        <FormField.Input
          as={TextInput}
          onChange={handleChange}
          placeholder="user@email.com"
          value={value}
        />
      </FormField.Field>
    </FormField>
  );
};

Accessibility Note: Always provide a persistent FormField.Label and never rely on placeholder text as the only label for an input. Placeholders can disappear or lack sufficient contrast. Use placeholders only for short format examples (e.g., “name@example.com”), and place detailed instructions or guidance in FormField.Hint instead of the placeholder.

Ref Forwarding

Text Input supports ref forwarding . It will forward ref to its underlying <input type="text"> element.

import React from 'react';

import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {FormField} from '@workday/canvas-kit-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

export default () => {
  const [value, setValue] = React.useState('');
  const ref = React.useRef(null);

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  const handleClick = () => {
    ref.current.focus();
  };

  return (
    <>
      <FormField>
        <FormField.Label>Email</FormField.Label>
        <FormField.Field>
          <FormField.Input as={TextInput} onChange={handleChange} ref={ref} value={value} />
        </FormField.Field>
      </FormField>
      <PrimaryButton onClick={handleClick}>Focus Text Input</PrimaryButton>
    </>
  );
};

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.

import React from 'react';

import {FormField} from '@workday/canvas-kit-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField grow>
      <FormField.Label>Street Address</FormField.Label>
      <FormField.Field>
        <FormField.Input as={TextInput} onChange={handleChange} value={value} />
      </FormField.Field>
    </FormField>
  );
};

Label Position Horizontal

Set the orientation prop of the Form Field to designate the position of the label relative to the input component. By default, the orientation will be set to vertical.

import React from 'react';

import {FormField} from '@workday/canvas-kit-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField orientation="horizontalStart">
      <FormField.Label>Email</FormField.Label>
      <FormField.Field>
        <FormField.Input as={TextInput} onChange={handleChange} value={value} />
        <FormField.Hint>Add a valid email</FormField.Hint>
      </FormField.Field>
    </FormField>
  );
};

Required

Set the isRequired 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.

import React from 'react';

import {FormField} from '@workday/canvas-kit-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';

export default () => {
  const [value, setValue] = React.useState('');

  const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
    setValue(event.target.value);
  };

  return (
    <FormField isRequired={true}>
      <FormField.Label>Email</FormField.Label>
      <FormField.Field>
        <FormField.Input as={TextInput} onChange={handleChange} value={value} />
      </FormField.Field>
    </FormField>
  );
};

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. Do not use the cs prop or any method to change width. The width prop is used to correctly position other inner elements.

Do not use FormField.Input as={InputGroup} — that breaks label association. Render FormField.Field as={InputGroup}, hoist the input id from the Form Field model, and set it on InputGroup.Input (see the Icons example).

import React from 'react';

import {
  FormField,
  useFormFieldInput,
  useFormFieldModel,
} from '@workday/canvas-kit-react/form-field';
import {SystemIcon} from '@workday/canvas-kit-react/icon';
import {InputGroup} from '@workday/canvas-kit-react/text-input';
import {mailIcon} from '@workday/canvas-system-icons-web';

/**
 * Using `as={InputGroup}` on `FormField.Input` will break the label associations necessary for accessibility.
 * In this example, we've rendered `FormField.Field` as `InputGroup` and then hoisted the `id` of the input from the FormField model.
 * This allows us to set the `id` of the `InputGroup.Input` correctly for proper label association.
 */

export default () => {
  const model = useFormFieldModel();
  const {id: formFieldInputId} = useFormFieldInput(model);

  return (
    <FormField model={model}>
      <FormField.Label>Email</FormField.Label>
      <FormField.Field as={InputGroup}>
        <InputGroup.InnerStart>
          <SystemIcon icon={mailIcon} />
        </InputGroup.InnerStart>
        <InputGroup.Input id={formFieldInputId} autoComplete="email" />
        <InputGroup.InnerEnd>
          <InputGroup.ClearButton />
        </InputGroup.InnerEnd>
      </FormField.Field>
    </FormField>
  );
};

Accessibility Note: Canvas Kit icons are already hidden from assistive technology — their SVG markup sets role="presentation" and focusable="false" — so decorative icons like the mail icon in this example need no extra attributes. If an icon conveys meaning beyond the label text, provide that meaning as text for screen readers.

Error States

Form Field provides error and caution states for Text Input. Set the error prop on Form Field to "error" or "caution" and use FormField.Hint to provide error messages. See Form Field’s Error documentation for examples and accessibility guidance.

Accessibility

The primary accessibility goal for TextInput is to give every user a visible, persistent label and clear instructions, and to ensure assistive technology users can identify the single-line field and hear hints, errors, required state, and input purpose when the control receives focus. Use TextInput for single-line values (names, emails, short answers). For multiple lines or paragraphs of text, use TextArea instead.

Minimum Accessible Structure

Build on the Basic example: label first, then the input inside FormField.Field. This order matches the DOM reading sequence and ensures the label’s htmlFor targets the <input> before hint text follows the control.

import {FormField} from '@workday/canvas-kit-react/form-field';
import {TextInput} from '@workday/canvas-kit-react/text-input';
 
<FormField>
  <FormField.Label>Email</FormField.Label>
  <FormField.Field>
    <FormField.Input as={TextInput} />
    <FormField.Hint>We'll never share your email.</FormField.Hint>
  </FormField.Field>
</FormField>;

Every TextInput requires FormField, a visible FormField.Label, and FormField.Input as={TextInput} so the control has a programmatically determinable name, relationships, and instructions. See FormField’s accessibility documentation for shared form-field guidance. Include FormField.Hint for instructions or validation messages—FormField associates that text with the input through aria-describedby.

Built-in Behaviors

Canvas Kit applies these automatically when you compose TextInput with FormField subcomponents (and InputGroup, when used). Do not duplicate them in consuming code.

ARIA and DOM (applied by subcomponents):

• TextInput: Renders a native <input type="text"> by default. Screen readers identify it as a single-line text input.
• TextInput disabled: Maps to the native disabled attribute; disabled fields are removed from the tab order.
• InputGroup.ClearButton: Sets role="presentation" and tabIndex={-1} so the control is not in the tab order and is not exposed as an operable button to screen readers. Clearing is available via native keyboard editing in the input.
• InputGroup.Input: Always ensures a placeholder attribute exists (empty string when unset) so :placeholder-shown styling for the clear button works correctly.
• Canvas Kit icons (for example SystemIcon inside InputGroup): SVG markup includes role="presentation" and focusable="false", which removes the implied img role. Decorative icons need no aria-hidden.

Keyboard (standard TextInput behavior):

TextInput uses native <input> keyboard behavior (tab order, label activation, and text-editing shortcuts). Do not add custom key handlers that prevent standard text editing.

InputGroup.ClearButton is intentionally not keyboard-focusable; users clear the value with standard input editing keys.

Screen reader expectations (when built-in behaviors are used as intended):

• On focus, assistive technology announces the field label and, when applicable: required state, invalid state (error="error"), and hint or error text via aria-describedby.
• The current value or “blank” is announced when the input receives focus.
• The Caution state is visual only — aria-invalid is not set for error="caution".
• Disabled inputs may be announced as unavailable and are skipped in the tab order.
• InputGroup.ClearButton is not announced as a separate operable control.
• Icons rendered inside InputGroup.InnerStart or InputGroup.InnerEnd are not announced, because their SVG markup uses role="presentation".

For rendered label, input, and hint association markup, see the DOM examples in FormField’s Built-in Behaviors. TextInput renders a native <input> (see FormField examples).

Accessibility Requirements

Required in application code for an accessible TextInput. Rows marked (conditional) apply only when the situation matches—otherwise omit.

If no design spec is provided: use a visible FormField.Label, wrap the control with FormField.Input as={TextInput}, omit isHidden, omit a custom id unless testing or composition requires it, omit a ref unless programmatic focus is required, and omit InputGroup unless icons or a clear control are part of the design.

Programmatic focus (conditional — omit by default):

Use a ref when the product needs to move focus to the input after an action (for example, focusing the field after a validation error, or a control that focuses the input). Do not attach a ref or call focus() unless the design or developer asks for it. See Ref Forwarding under Usage for a complete Storybook example.

const Example = () => {
  const ref = React.useRef<HTMLInputElement>(null);
 
  const handleClick = () => {
    ref.current?.focus();
  };
 
  return (
    <>
      <FormField>
        <FormField.Label>Email</FormField.Label>
        <FormField.Field>
          <FormField.Input as={TextInput} ref={ref} />
        </FormField.Field>
      </FormField>
      <PrimaryButton onClick={handleClick}>Focus Text Input</PrimaryButton>
    </>
  );
};

InputGroup with icons (conditional):

When the design includes start/end icons or a clear control, compose InputGroup as FormField.Field (not as FormField.Input) and wire the input id from the Form Field model:

import {
  FormField,
  useFormFieldInput,
  useFormFieldModel,
} from '@workday/canvas-kit-react/form-field';
import {SystemIcon} from '@workday/canvas-kit-react/icon';
import {InputGroup} from '@workday/canvas-kit-react/text-input';
import {mailIcon} from '@workday/canvas-system-icons-web';
 
const model = useFormFieldModel();
const {id: formFieldInputId} = useFormFieldInput(model);
 
<FormField model={model}>
  <FormField.Label>Email</FormField.Label>
  <FormField.Field as={InputGroup}>
    <InputGroup.InnerStart>
      <SystemIcon icon={mailIcon} />
    </InputGroup.InnerStart>
    <InputGroup.Input id={formFieldInputId} autoComplete="email" />
    <InputGroup.InnerEnd>
      <InputGroup.ClearButton />
    </InputGroup.InnerEnd>
  </FormField.Field>
</FormField>;

Summary for code generation:

• REQUIRED: visible label, FormField.Input as={TextInput} wiring
• CONDITIONAL: autoComplete, specialized type, InputGroup icon/clear composition with hoisted id, programmatic focus via ref. See FormField accessibility for shared FormField conditionals (hint/error, required, disabled, placeholder, stable id).

Anti-Patterns

Do not generate code that does the following (see Accessibility Requirements above for what to supply instead):

• Unlabeled text inputs: Do not use TextInput without FormField and FormField.Label (see Minimum accessible structure). For shared FormField anti-patterns (manual ARIA wiring, placeholder-only labels, color-only errors, broken ID references), see FormField Anti-Patterns.
• Multi-line content in TextInput: Do not use TextInput when the user needs to enter paragraphs or multi-line text; use TextArea instead.
• FormField.Input as={InputGroup}: Do not put InputGroup on FormField.Input — that breaks label association. Use FormField.Field as={InputGroup}, hoist id from useFormFieldInput(model), and pass it to InputGroup.Input (see InputGroup with icons in Accessibility Requirements and Icons under Usage).
• Re-wiring ClearButton a11y: Do not override InputGroup.ClearButton’s role or tabIndex to make it a focusable, announced button — Canvas Kit intentionally keeps clearing on the input.
• Redundant aria-hidden on icons: Do not add aria-hidden to Canvas Kit icons — their SVG markup already sets role="presentation" and focusable="false".
• Meaningful icons without a text alternative: Do not rely on an icon inside InputGroup to convey information beyond the label; because icons are presentational, that meaning must come from text such as FormField.Label or FormField.Hint.
• Programmatic focus by default: Do not attach a ref or call focus() on the input unless the design or developer asks for it (see Programmatic focus in Accessibility Requirements).

Component API

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

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

InputGroupInnerStart

InputGroupInput

InputGroupInnerEnd

ClearButton

Content Guidelines

• Labels for Text Inputs are written in title case.