Luke UI
On this page

Forms

Text Input Field

Captures a single line of text with a label, validation, and an optional prefix or suffix.

React AriaSourceView as MarkdownEdit on GitHub

Use TextInputField to collect a single line of text. It combines an input with a label, description, and validation message.

Text Input Field: Basic
Open in playground
Use the address you check most often.
import { TextInputField } from '@luke-ui/react/text-input-field';

export default () => {
	return (
		<TextInputField
			description="Use the address you check most often."
			label="Email address"
			name="emailAddress"
			placeholder="[email protected]"
		/>
	);
};

Labels and placeholders

Give the field a visible label where possible. Use placeholder for an example value or input format, not as the label. A placeholder disappears while someone types and is not a reliable accessible name.

When a nearby heading already names the field, omit label. Use aria-label or aria-labelledby instead.

<TextInputField aria-label="Search" name="search" placeholder="Search" />

Required fields

Set isRequired when the field must have a value. By default, a required text input shows a marker after its label. Read Required fields for the necessityIndicator values.

Text Input Field: Required
Open in playground
import { Stack } from '@luke-ui/react/stack';
import { TextInputField } from '@luke-ui/react/text-input-field';

export default () => {
	return (
		<Stack gap="space.16">
			<TextInputField
				isRequired
				label="First name"
				name="firstName"
				necessityIndicator="required-asterisk"
			/>
			<TextInputField
				isRequired
				label="Last name"
				name="lastName"
				necessityIndicator="required-label"
			/>
			<TextInputField label="Middle name" name="middleName" necessityIndicator="optional-label" />
		</Stack>
	);
};

Validation

Set isRequired, type, or pattern, or pass validate to check the value. TextInputField shows its validation message after validation fails. Pass errorMessage only for an error you already have, such as one from a form library or your server. A non-empty message marks the field invalid. Read Validation for where messages come from, server errors, and how to write them.

Text Input Field: Validation
Open in playground
import { Button } from '@luke-ui/react/button';
import { Cluster } from '@luke-ui/react/cluster';
import { Stack } from '@luke-ui/react/stack';
import { TextInputField } from '@luke-ui/react/text-input-field';
import type { SubmitEvent } from 'react';

function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
	event.preventDefault();
}

export default () => {
	return (
		<form onSubmit={handleSubmit}>
			<Stack gap="space.16">
				<TextInputField isRequired label="Email address" name="emailAddress" type="email" />
				<Cluster>
					<Button type="submit">Submit</Button>
				</Cluster>
			</Stack>
		</form>
	);
};

Prefix and suffix

Use prefix and suffix for content inside the input, such as a search icon, currency code, or URL scheme. Both accept any ReactNode. Give an interactive prefix or suffix an accessible name and keyboard behaviour.

Text Input Field: Prefix and suffix
Open in playground
import { Icon } from '@luke-ui/react/icon';
import { Stack } from '@luke-ui/react/stack';
import { TextInputField } from '@luke-ui/react/text-input-field';

export default () => {
	return (
		<Stack gap="space.16">
			<TextInputField
				label="Search documentation"
				name="documentationSearch"
				placeholder="Search components"
				prefix={<Icon name="search" size="small" />}
			/>
			<TextInputField label="Website" name="website" placeholder="example.com" prefix="https://" />
			<TextInputField label="Budget" name="budget" placeholder="0.00" suffix="AUD" />
		</Stack>
	);
};

Size

Use size to set the input height and typography. Use small in compact layouts. medium is the default. The HTML numeric size attribute is unavailable because size is the Luke UI variant. On touch devices, small uses the body text size so iOS Safari doesn't zoom into the field on focus.

Text Input Field: Size
Open in playground
small
medium
import { TextInputField } from '@luke-ui/react/text-input-field';
import { Comparison, ComparisonItem } from '#docs';

export default () => {
	return (
		<Comparison>
			<ComparisonItem label="small">
				<TextInputField
					label="Example field"
					name="example"
					placeholder="Example input"
					size="small"
				/>
			</ComparisonItem>
			<ComparisonItem label="medium">
				<TextInputField
					label="Example field"
					name="example"
					placeholder="Example input"
					size="medium"
				/>
			</ComparisonItem>
		</Comparison>
	);
};

IDs and refs

id, className, and ref target the field's root element. Pass inputId to set the input's id, and inputRef to reach the input.

Accessibility

Luke UI associates the label, description, and error message with the control.

API

TextInputFieldProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

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

description
ReactNode—

Optional helper text shown below the control.

errorMessage
ReactNode—

Validation message for a controlled error. A non-empty message marks the field invalid.

inputClassName
ClassNameOrFunction<InputRenderProps> |⁠ undefined—

Class name forwarded to the inner input element.

inputId
string |⁠ undefined—

Element id for the input. The field generates one when omitted.

inputRef
Ref<HTMLInputElement>—

Forwarded to the inner <input> element. Accepts a callback ref or a ref object. Use ref for the root element.

label
Exclude<ReactNode, boolean |⁠ null |⁠ undefined>—

Visible label. Pass non-empty, textual, non-interactive content. Place links and buttons outside it, and associate external label content with aria-labelledby instead.

necessityIndicator
—

Controls how the label identifies required or optional values. Inherits from Form, or uses 'required-asterisk' when unset.

placeholder
string—

Placeholder text for the input.

prefix
ReactNode—

Element shown before the input value.

size
'medium'

Control size.

spellCheck
string—

An enumerated attribute that defines whether the element may be checked for spelling errors. See MDN.

suffix
ReactNode—

Element shown after the input value.