# TextField
A labeled one-line text input on the Field contract: pass `label`, and `error` from your server action or client check. The `type` sets the phone keyboard and autofill, `password` gets a show/hide button that keeps focus in the input, `clearable` adds a clear button, and `startAdornment`/`endAdornment` put text or icons inside the box.
```tsx
import { TextField } from "@/components/ouro/text-field/text-field";
```
## Example
```tsx
} />
// A hero search: the row draws the rules, the field has no frame and large text.
```
## Usage
Not here, because each has its own component:
- Numbers: `NumberField` parses, steps and formats them. A digit code (a PIN, a postcode) stays a TextField with `inputMode="numeric"`, or is an `OtpField`.
- A date picked from a calendar: `DatePicker`. `type="date"` here opens the OS picker.
- A date and time together: there is no `datetime-local`. Use a `DatePicker` and a `type="time"` TextField side by side, and join the two values on the server.
- Files: `FileField`.
- Several lines: `TextArea`.
`variant="plain"` draws no frame, and `size="lg"` sets 20px text: together they put the field inside a row your app frames, such as a page's main search between two rules.
## Use instead when
- Use `TextArea` instead for several lines, `NumberField` for numbers, `DatePicker` for a date picked from a calendar, `FileField` for files, and `Field` with `FieldControl` when the control is not a text input.
## Props
Type: `TextFieldProps`.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | | Layout only: margins, width, grid placement (`mt-4`, `col-span-2`). Appearance classes warn in development; style fields in your theme. |
| `clearable` | `boolean` | | Adds a button that empties the field and puts focus back in it. It shows while there is text. |
| `clearLabel` | `string` | `"Clear"` | The name of the clear button that `clearable` adds, as visually hidden text. Translate it with your app. |
| `description` | `ReactNode` | | Supporting text under the label, read after the label through `aria-describedby`. |
| `disabled` | `boolean` | | Disables the field, its buttons included, and fades it. |
| `endAdornment` | `ReactNode` | | Text or an icon inside the box, after the input: `"kg"`, ``. Text is also read as part of the description. |
| `error` | `ReadonlyErrorMessages` | | What is wrong, from your server action or client check. The message (or several, as a list) shows under the field, which gets `aria-invalid`. A message is text or a React node (one with a link); an empty string or array means valid. |
| `hideLabel` | `boolean` | | Hides the label visually; screen readers still read it as the field's name. |
| `label` (required) | `string` | | What the field is for, shown above it and read as its name. Required: every control needs a name. To hide it visually, keep it and add `hideLabel`. A placeholder is not a label. |
| `name` | `string` | | The form field name the value submits under. |
| `placeholder` | `string` | | An example of what to type, shown while the field is empty: `"you@example.com"`. It is not a label; pass `label`, which stays visible. |
| `ref` | `Ref` | | The input element. |
| `required` | `boolean` | | The field must be filled: it gets `required` and `aria-required`, and the label a marker. |
| `showPasswordLabel` | `string` | `"Show password"` | The name of a password field's show/hide button, as visually hidden text and not an `aria-label`, so a test's `getByLabel("Password")` finds the input alone; find the button with `getByRole("button", { name: "Show password" })`. It stays the same while the password shows; the button's pressed state (`aria-pressed`) says whether it does. Translate it with your app. |
| `size` | `"md" \| "lg"` | `"md"` | Control size. `md` is 44px tall with 16px text on phones and steps down to desktop density from the `sm` breakpoint (640px). `lg` is 56px tall (48px on desktop) with 20px text at every width, for a page's main search. The font family is inherited, so set a display font on a parent. It replaces the input's own `size` attribute (a width in characters); set the width with `className`. |
| `startAdornment` | `ReactNode` | | Text or an icon inside the box, before the input: `"$"`, ``. Text is also read as part of the field's description. Replaces shadcn's InputGroup. |
| `type` | `"text" \| "url" \| "date" \| "time" \| "search" \| "email" \| "password" \| "tel"` | `"text"` | What kind of text it holds. Each type sets the phone keyboard (`inputMode`) and autofill (`autoComplete`) for you; pass either to override. `password` adds a show/hide button; `date` and `time` open the OS picker. Other kinds of value have their own component: `NumberField` for numbers (`inputMode="numeric"` here for digit codes), `DatePicker` for a date picked from a calendar, `DatePicker` beside a `type="time"` TextField for a date and time (there is no `datetime-local`), and `FileField` for files. Any other string is a type error whose message names them. |
| `variant` | `"outline" \| "plain"` | `"outline"` | The frame. `outline` draws the bordered box. `plain` draws no border, background or side padding, for a field inside a frame your app draws (a search row with its own rules and a button beside the input); it keeps the focus outline, and the error message still shows under it, but with no border to turn red, color your own frame for an invalid field. Any other string is a type error whose message names the fix. |
## Native attributes
Also accepts the attributes in React's `HTMLAttributes` and `InputHTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.
## Don't use
These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.
- `endIcon`: Not a prop. Ouro UI uses `endAdornment`: `}>`.
- `errorMessage`: Not a prop. Ouro UI uses `error`: ``.
- `helperText`: Not a prop. Ouro UI uses `description`: ``.
- `invalid`: Not a prop. `error` marks the field invalid: ``.
- `isClearable`: Not a prop. Ouro UI uses `clearable`: ``.
- `isDisabled`: Not a prop. Ouro UI uses `disabled`: ``.
- `isInvalid`: Not a prop. `error` marks the field invalid: ``.
- `isRequired`: Not a prop. Ouro UI uses `required`: ``.
- `leftIcon`: Not a prop. Ouro UI uses `startAdornment`: `}>`.
- `multiline`: Not a prop. TextField is one line; use `TextArea` for several: ``.
- `prefix`: Not a prop. Ouro UI uses `startAdornment`: ``.
- `rightIcon`: Not a prop. Ouro UI uses `endAdornment`: `}>`.
- `startIcon`: Not a prop. Ouro UI uses `startAdornment`: `}>`.
- `suffix`: Not a prop. Ouro UI uses `endAdornment`: ``.
## `className` is for layout only
Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`). Your classes always win over Ouro UI's: TextField merges `className` last with `cn` (tailwind-merge), so a class that conflicts with its own replaces it.[^layout-classes]
Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.
Alignment classes (`text-center`) warn too: set alignment on a parent element.
## Types
### `ErrorMessage`
One error message: text, or a React element for a message that carries a link or other markup.
```ts
type ErrorMessage = string | ReactElement;
```
### `ReadonlyErrorMessages`
A read-only message view accepted by fields and Form; mutable input arrays remain valid.
```ts
type ReadonlyErrorMessages = ErrorMessage | readonly ErrorMessage[];
```
[^layout-classes]: test:registry/ouro/components/ouro/text-field/text-field.test.tsx::TextField > lets app layout classes win on the root verify:testExists(registry/ouro/components/ouro/text-field/text-field.test.tsx::TextField > lets app layout classes win on the root)