@workday/canvas-kit-docs/dist/mdx/react/text-input/TextInput.mdx

Documentation components of Canvas Kit components

import {
  ExampleCodeBlock,
  InformationHighlight,
  SymbolDoc,
  Specifications,
} from '@workday/canvas-kit-docs';
import Alert from './examples/Alert';
import Basic from './examples/Basic';
import Disabled from './examples/Disabled';
import Error from './examples/Error';
import Grow from './examples/Grow';
import LabelPosition from './examples/LabelPosition';
import Placeholder from './examples/Placeholder';
import RefForwarding from './examples/RefForwarding';
import Required from './examples/Required';
import Icons from './examples/Icons';


# Canvas Kit Text Input

Text Inputs allow users to enter words or characters without styling.

[> Workday Design Reference](https://design.workday.com/components/inputs/text-input)

## Installation

```sh
yarn add @workday/canvas-kit-react
```

## Usage

### Basic Example

Text Input should be used in tandem with [Form Field](/components/inputs/form-field/) to meet
accessibility standards.

<ExampleCodeBlock code={Basic} />

### Disabled

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

<ExampleCodeBlock code={Disabled} />

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

<ExampleCodeBlock code={Placeholder} />

### Ref Forwarding

Text Input supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will forward
`ref` to its underlying `<input type="text">` element.

<ExampleCodeBlock code={RefForwarding} />

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

<ExampleCodeBlock code={Grow} />

The `grow` prop may also be applied directly to the Text Input if Form Field is not being used.

### 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`.

<ExampleCodeBlock code={LabelPosition} />

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

<ExampleCodeBlock code={Required} />

### 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](https://developer.mozilla.org/en-US/docs/Web/CSS/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.

<ExampleCodeBlock code={Icons} />

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

<ExampleCodeBlock code={Alert} />

#### Error

<ExampleCodeBlock code={Error} />

## Component API

<SymbolDoc name="TextInput" fileName="/react/" />

<SymbolDoc name="InputGroup" fileName="/react/" />

## Specifications

<Specifications file="TextInput.spec.ts" name="TextInput" />