# TextInput primitives (/components/primitives/text-input)
Use these primitives to build a custom text input. For most application forms, use
[`TextInputField`](/components/forms/text-input-field).
apps/docs/src/examples/text-input-primitive/basic.tsx
```tsx
import {
TextInput,
TextInputControl,
TextInputPrefix,
TextInputSuffix,
} from '@luke-ui/react/primitives/text-input';
export default () => {
return (
$USD
);
};
```
## Anatomy [#anatomy]
`TextInputRoot` is the semantic root. It connects the input to the label, description, and error
inside it, and owns the value, state, and validation. `TextInput` is the ``.
`TextInputControl` is optional chrome around the input and its `TextInputPrefix` and
`TextInputSuffix`. Parts follow document order, so put the prefix before the input and the suffix
after it.
```tsx
$USD
```
## Choosing a composition [#choosing-a-composition]
Make two independent choices.
- **A root or no root.** Wrap the input in `TextInputRoot` to connect it to `Field`, or to
`FieldLabel`, `FieldDescription`, and `FieldError`, with no manual ids. Without a root,
`TextInput` takes native input props such as `name`, `value`, `onChange`, `disabled`, and
`aria-invalid`, and needs an accessible name from `aria-label` or a connected label.
- **A control or no control.** Wrap the input in `TextInputControl` to add a prefix or suffix. The
control draws the chrome, and the input inside it is transparent. Without a control, `TextInput`
draws its own chrome.
apps/docs/src/examples/text-input-primitive/with-root.tsx
```tsx
import { FieldDescription, FieldError, FieldLabel } from '@luke-ui/react/primitives/field';
import { TextInput, TextInputRoot } from '@luke-ui/react/primitives/text-input';
import { Stack } from '@luke-ui/react/stack';
export default () => {
return (
Email addressWe send receipts to this address.
);
};
```
A prefix or suffix accepts any React node, including an interactive one such as a button. Give an
interactive part an accessible name, keyboard behaviour, and a considered focus order.
## Root and input props [#root-and-input-props]
The root owns the state and semantics that span the field. A `TextInput` inside it ignores its own
values for these props:
- `id`. Set `inputId` on the root.
- `value` and `defaultValue`.
- `name` and `form`.
- `disabled`, `readOnly`, and `required`. Set `isDisabled`, `isReadOnly`, and `isRequired` on the
root.
- `aria-invalid`. Set `isInvalid` or a validation prop on the root.
- `type`, `pattern`, `minLength`, and `maxLength`. Set them on the root, because they are part of
the field's validation.
`aria-describedby` and `aria-labelledby` on a `TextInput` inside a `TextInputRoot` add to the
field's own wiring. They never replace the connection to the label, description, and error.
The root passes `autoComplete`, `inputMode`, `autoCorrect`, `spellCheck`, `enterKeyHint`,
`autoFocus`, `aria-label`, and `size` down to the input as defaults. Set one on the `TextInput` to
override the root's for that input.
```tsx
```
Set input-only props such as `placeholder`, `autoCapitalize`, `className`, `style`, and `ref` on the
`TextInput`. Event handlers on the input run alongside the root's. An `onChange` on the input
receives the change event, while the root's `onChange` receives the value.
`id` and `ref` on `TextInputRoot` target the root element. Pass `inputId` to set the input's id.
## Size [#size]
`medium` is the default. Use `small` in compact layouts. `size` on `TextInputRoot` sets the default
for the parts inside it. A `TextInput` or `TextInputControl` with its own `size` overrides the
root's. Inside a control, the control sets the size, and the input, prefix, and suffix follow it.
On touch devices, `small` uses the body text size so iOS Safari doesn't zoom into the field on
focus.
The control also sets the icon size for everything inside it, so an `Icon` in a prefix or suffix
scales with the control without a `size` of its own.
## Validation [#validation]
Mark a standalone `TextInput` invalid with `aria-invalid`. Inside a root, the root sets the invalid
state. Outside a control, an invalid input draws a thicker border that does not change its size.
`TextInputControl` has no invalid prop. It reads invalid state from the input inside it and takes a
danger border.
An input inside a `TextInputRoot` gets its message from `FieldError`, which carries the error icon
and says what is wrong. A standalone invalid input relies on its structural border, so the
surrounding interface should explain the problem. See [Validation](/docs/validation).
## API [#api]
### TextInputRootProps [#textinputrootprops]
### TextInputRootProps
Props for `TextInputRoot`.
`TextInputRootProps` also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.
| Prop | Type | Description |
| ------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `aria-label?` | `string` | Defines a string value that labels the current element. |
| `aria-labelledby?` | `string` | Identifies the element (or elements) that labels the current element. |
| `aria-describedby?` | `string` | Identifies the element (or elements) that describes the object. |
| `aria-details?` | `string` | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `aria-errormessage?` | `string` | Identifies the element that provides an error message for the object. |
| `onCopy?` | `React.ClipboardEventHandler` | Handler that is called when the user copies text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy). |
| `onCut?` | `React.ClipboardEventHandler` | Handler that is called when the user cuts text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut). |
| `onPaste?` | `React.ClipboardEventHandler` | Handler that is called when the user pastes text. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste). |
| `onCompositionStart?` | `React.CompositionEventHandler` | Handler that is called when a text composition system starts a new text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event). |
| `onCompositionEnd?` | `React.CompositionEventHandler` | Handler that is called when a text composition system completes or cancels the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event). |
| `onCompositionUpdate?` | `React.CompositionEventHandler` | Handler that is called when a new character is received in the current text composition session. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event). |
| `onSelect?` | `React.ReactEventHandler` | Handler that is called when text in the input is selected. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event). |
| `onBeforeInput?` | `React.FormEventHandler` | Handler that is called when the input value is about to be modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event). |
| `onInput?` | `React.FormEventHandler` | Handler that is called when the input value is modified. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event). |
| `autoComplete?` | `string` | Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete). |
| `maxLength?` | `number` | The maximum number of characters supported by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength). |
| `minLength?` | `number` | The minimum number of characters required by the input. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength). |
| `pattern?` | `string` | Regex pattern that the value of the input must match to be valid. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern). |
| `type?` | `'text' \| 'search' \| 'url' \| 'tel' \| 'email' \| 'password' \| (string & {})` | The type of input to render. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype). Default: `'text'` |
| `inputMode?` | `'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'` | Hints at the type of data that might be entered by the user while editing the element or its contents. See [MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute). |
| `autoCorrect?` | `string` | An attribute that takes as its value a space-separated string that describes what, if any, type of autocomplete functionality the input should provide. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete). |
| `spellCheck?` | `string` | An enumerated attribute that defines whether the element may be checked for spelling errors. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck). |
| `onKeyDown?` | `(e: KeyboardEvent) => void` | Handler that is called when a key is pressed. |
| `onKeyUp?` | `(e: KeyboardEvent) => void` | Handler that is called when a key is released. |
| `onFocus?` | `(e: React.FocusEvent) => void` | Handler that is called when the element receives focus. |
| `onBlur?` | `(e: React.FocusEvent) => void` | Handler that is called when the element loses focus. |
| `onFocusChange?` | `(isFocused: boolean) => void` | Handler that is called when the element's focus status changes. |
| `autoFocus?` | `boolean` | Whether the element should receive focus on render. |
| `slot?` | `string \| null` | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. |
| `aria-activedescendant?` | `string` | Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application. |
| `aria-autocomplete?` | `'none' \| 'inline' \| 'list' \| 'both'` | Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be presented if they are made. |
| `enterKeyHint?` | `'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send'` | An enumerated attribute that defines what action label or icon to preset for the enter key on virtual keyboards. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint). |
| `children?` | `ChildrenOrFunction` | The field's parts, such as `Field` or `FieldLabel`, and a `TextInput`. |
| `className?` | `ClassNameOrFunction \| undefined` | Class name for the root element. |
| `defaultValue?` | `string \| undefined` | Initial value (uncontrolled). |
| `form?` | `string \| undefined` | The `