# TextField
## Summary
`TextField` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) for single-line text entry. The root provides shared size and error state, while `TextFieldInput` owns the native input element. It is the base single-line field wrapper that other specialized text-entry controls build on.
## Imports
```tsx
import {
TextField,
TextFieldInput,
type TextFieldInputProps,
type TextFieldProps,
type TextFieldSize,
} from '@vega-ui/react';
```
## Exported Types
- `TextFieldProps`
- `TextFieldInputProps`
- `TextFieldSize = 'sm' | 'md' | 'lg' | string`
## Minimal Composition
```tsx
import { HelperText, Label, TextField, TextFieldInput } from '@vega-ui/react';
import { useId } from 'react';
export default function WorkEmailField() {
const id = useId();
const hintId = `${id}-hint`;
return (
Invoices and security alerts are sent here.
);
}
```
## Required Parts
- `TextField`: layout wrapper with size and error context
- `TextFieldInput`: native input element
## Optional Parts
- prefix or suffix children such as `Button`, `IconButton`, counters, or status text
## Composition Order
1. `TextField`
2. optional leading child
3. `TextFieldInput`
4. optional trailing child
## Variants
- Size: `sm`, `md`, `lg`
- State: default, `error`, disabled input
- Composition: plain input, prefix/suffix controls, controlled or uncontrolled value
## Edge Cases
- `TextField` itself is not the input; form attributes belong on `TextFieldInput`.
- Prefix and suffix actions change hit area and layout density, so they should be intentional.
- Error visuals live on the wrapper, but input semantics still belong to the native input.
- Once masking, password reveal, numeric stepping, or phone formatting become part of the field contract, a specialized field is usually clearer than stretching `TextField`.
## Common Mistakes
- Passing `value`, `onChange`, or `name` to `TextField` instead of `TextFieldInput`.
- Rendering the wrapper without `TextFieldInput`.
- Treating prefix/suffix children as decorative when they change interaction behavior.
## Examples
### Basic
#### Basic: work email with a hint
A visible `Label` points at `TextFieldInput` through `htmlFor`, and the hint is linked with `aria-describedby`. All input attributes — `type`, `name`, `autoComplete` — go on `TextFieldInput`, not on the wrapper. Ids come from `useId`, so several fields on one page never collide.
```tsx
import { HelperText, Label, TextField, TextFieldInput } from '@vega-ui/react';
import { useId } from 'react';
export default function WorkEmailField() {
const id = useId();
const hintId = `${id}-hint`;
return (
Invoices and security alerts are sent here.
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: character counter suffix
The parent owns the value, so the counter in the suffix and the preview below stay in sync with every keystroke. `maxLength` stops typing at the limit, and the counter is linked to the input with `aria-describedby`.
```tsx
import { Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { useId, useState } from 'react';
const MAX_LENGTH = 60;
export default function CharacterCounterSuffix() {
const id = useId();
const counterId = `${id}-counter`;
const [title, setTitle] = useState('Q3 roadmap review');
const remaining = MAX_LENGTH - title.length;
return (
);
}
```
### Form/Integration
#### Form/Integration: profile form with FormData
Uncontrolled inputs with `name` and `defaultValue` are read with `FormData` on submit. `required` and `type='email'` use native validation, and a reset button restores the default values.
```tsx
import { Button, Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
export default function ProfileFormSubmit() {
const id = useId();
const [saved, setSaved] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
setSaved(`${data.get('fullName')} <${data.get('email')}>`);
};
return (
);
}
```
#### Form/Integration: search with clear and submit
A `role='search'` form with a leading icon, a clear button that returns focus to the input, and a submit button — all inside one `TextField`. The input has no visible label, so it gets an `aria-label`.
```tsx
import type { CSSProperties, FormEvent } from 'react';
import { Button, Icon, IconButton, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { SearchIcon, XIcon } from '@vega-ui/icons';
import { useRef, useState } from 'react';
import './examples.css';
export default function SearchWithClearAndSubmit() {
const inputRef = useRef(null);
const [query, setQuery] = useState('');
const [searched, setSearched] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
setSearched(query.trim());
};
const clear = () => {
setQuery('');
inputRef.current?.focus();
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: rename inside a dialog
A `method='dialog'` form closes the dialog on submit, and `onSubmit` reads the new name with `FormData`. `autoFocus` puts the caret straight into the field when the dialog opens.
```tsx
import type { CSSProperties, FormEvent } from 'react';
import {
Button,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Heading,
Icon,
IconButton,
Label,
Text,
TextField,
TextFieldInput,
} from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';
import { useId, useState } from 'react';
export default function RenameInDialog() {
const id = useId();
const [name, setName] = useState('Mobile app redesign');
const onSubmit = (event: FormEvent) => {
const next = String(new FormData(event.currentTarget).get('projectName')).trim();
if (next !== '') setName(next);
};
return (
{name}
);
}
```
### Error
#### Error: email validated on blur and submit
The error appears on blur or submit and is re-checked on each keystroke while it is shown, so it clears as soon as the address becomes valid. `error` only paints the wrapper; `aria-invalid` and `aria-describedby` on the input carry the state to screen readers.
```tsx
import { Button, HelperText, Label, TextField, TextFieldInput } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
const getEmailError = (value: string) => {
if (value.trim() === '') return 'Enter an email address to send the invite.';
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return 'Use the full address, like dana@northwind.io.';
return '';
};
export default function EmailValidationError() {
const id = useId();
const messageId = `${id}-message`;
const [email, setEmail] = useState('dana@northwind');
const [error, setError] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
setError(getEmailError(email));
};
const onChange = (value: string) => {
setEmail(value);
if (error !== '') setError(getEmailError(value));
};
const invalid = error !== '';
return (
);
}
```
### Disabled
#### Disabled: read-only versus disabled
A read-only input stays focusable and is submitted with the form; a disabled one is skipped by focus and left out of `FormData`. Submit the form to see which fields arrive.
```tsx
import { Button, HelperText, Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
export default function ReadOnlyAndDisabled() {
const id = useId();
const [submitted, setSubmitted] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
const keys = Array.from(new FormData(event.currentTarget).keys());
setSubmitted(keys.join(', '));
};
return (
);
}
```
### Edge
#### Edge: async availability check
A debounced check runs 600 ms after the last keystroke, and the cleanup drops stale timers. The suffix shows a `Spinner` while checking, and the hint is a polite live region, so the result is announced.
```tsx
import { HelperText, Icon, Label, Spinner, TextField, TextFieldInput } from '@vega-ui/react';
import { CheckIcon } from '@vega-ui/icons';
import { useEffect, useId, useState } from 'react';
const TAKEN = ['admin', 'support', 'maria', 'billing'];
interface CheckResult {
username: string;
available: boolean;
}
export default function AsyncUsernameCheck() {
const id = useId();
const statusId = `${id}-status`;
const [username, setUsername] = useState('');
const [result, setResult] = useState(null);
const normalized = username.trim().toLowerCase();
useEffect(() => {
if (normalized.length < 3) return;
const timer = setTimeout(() => {
setResult({ username: normalized, available: !TAKEN.includes(normalized) });
}, 600);
return () => clearTimeout(timer);
}, [normalized]);
const tooShort = normalized.length < 3;
const checking = !tooShort && result?.username !== normalized;
const taken = !tooShort && !checking && result?.available === false;
const available = !tooShort && !checking && result?.available === true;
let message = 'At least 3 characters. Try “maria” to see a taken name.';
if (checking) message = 'Checking availability…';
if (available) message = `@${normalized} is available.`;
if (taken) message = `@${normalized} is already taken.`;
return (
);
}
```
#### Edge: long value between a prefix and a suffix
Static affixes keep their width while the input shrinks (`minWidth: 0`) and scrolls a long value. The affixes are hidden from screen readers because the hint spells out the full address.
```tsx
import { HelperText, Label, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { useId, useState } from 'react';
const affixStyle = {
flexShrink: 0,
whiteSpace: 'nowrap',
color: 'var(--label-secondary)',
} as const;
export default function SubdomainPrefixSuffix() {
const id = useId();
const hintId = `${id}-hint`;
const [subdomain, setSubdomain] = useState('northwind-traders-international-logistics');
const onChange = (value: string) => {
setSubdomain(value.toLowerCase().replace(/[^a-z0-9-]/g, ''));
};
return (
);
}
```
#### Edge: right-to-left layout
Under `dir='rtl'` the leading icon moves to the right because the field uses logical insets. The email input keeps `dir='ltr'`, since addresses are always written left to right.
```tsx
import { HelperText, Icon, Label, TextField, TextFieldInput } from '@vega-ui/react';
import { SearchIcon } from '@vega-ui/icons';
import { useId } from 'react';
export default function RtlField() {
const id = useId();
return (
כתובות דוא״ל נכתבות תמיד משמאל לימין.
);
}
```
## Anatomy
### Overview
`TextField` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) with a small composition contract. The wrapper coordinates sizing and visual state, and `TextFieldInput` provides the real form control.
### Required Parts
#### `TextField`
Required. Owns shared size, error state, and the visual container.
#### `TextFieldInput`
Required. Renders the native `` and receives actual input props.
### Optional Parts
#### Prefix Or Suffix Children
Optional. Buttons, icons, counters, or status text can be placed before or after the input.
### Composition Order
1. `TextField`
2. optional prefix child
3. `TextFieldInput`
4. optional suffix child
### Valid Composition Patterns
```tsx
import type { CSSProperties, FormEvent } from 'react';
import { Button, Icon, IconButton, Text, TextField, TextFieldInput } from '@vega-ui/react';
import { SearchIcon, XIcon } from '@vega-ui/icons';
import { useRef, useState } from 'react';
import './examples.css';
export default function SearchWithClearAndSubmit() {
const inputRef = useRef(null);
const [query, setQuery] = useState('');
const [searched, setSearched] = useState('');
const onSubmit = (event: FormEvent) => {
event.preventDefault();
setSearched(query.trim());
};
const clear = () => {
setQuery('');
inputRef.current?.focus();
};
return (
);
}
```
### Invalid Composition Patterns
#### Wrapper without `TextFieldInput`
The component renders, but there is no actual form control.
#### Input props passed to the wrapper
This breaks form behavior because the wrapper is only a `
`.
#### Too many competing controls around the input
The field becomes visually dense and hard to use.