useTextField
Provides the behavior and accessibility implementation for a text field.
install | yarn add @react-aria/textfield |
---|---|
version | 3.5.5 |
usage | import {useTextField} from '@react-aria/textfield' |
API#
useTextField<T extends TextFieldIntrinsicElements = DefaultElementType>(
(props: AriaTextFieldOptions<T>,
, ref: TextFieldRefObject<T>
)): TextFieldAria<T>
Features#
Text fields can be built with <input>
or <textarea>
and <label> elements,
but you must manually ensure that they are semantically connected via ids for accessibility.
useTextField
helps automate this, and handle other accessibility features while
allowing for custom styling.
- Built with a native
<input>
or<textarea>
element - Visual and ARIA labeling support
- Change, clipboard, composition, selection, and input event support
- Required and invalid states exposed to assistive technology via ARIA
- Support for description and error message help text linked to the input via ARIA
Anatomy#
Text fields consist of an input element and a label. useTextField
automatically manages
the relationship between the two elements using the for
attribute on the <label>
element
and the aria-labelledby
attribute on the <input>
element.
useTextField
also supports optional description and error message elements, which can be used
to provide more context about the field, and any validation messages. These are linked with the
input via the aria-describedby
attribute.
useTextField
returns props that you should spread onto the appropriate element:
Name | Type | Description |
inputProps | TextFieldInputProps<TextFieldIntrinsicElements> | Props for the input element. |
labelProps | LabelHTMLAttributes<HTMLLabelElement> | Props for the text field's visible label element, if any. |
descriptionProps | HTMLAttributes<HTMLElement> | Props for the text field's description element, if any. |
errorMessageProps | HTMLAttributes<HTMLElement> | Props for the text field's error message element, if any. |
If there is no visual label, an aria-label
or aria-labelledby
prop must be passed instead
to identify the element to screen readers.
Example#
import {useTextField} from '@react-aria/textfield';
function TextField(props) {
let { label } = props;
let ref = React.useRef();
let { labelProps, inputProps, descriptionProps, errorMessageProps } =
useTextField(props, ref);
return (
<div style={{ display: 'flex', flexDirection: 'column', width: 200 }}>
<label {...labelProps}>{label}</label>
<input {...inputProps} ref={ref} />
{props.description && (
<div {...descriptionProps} style={{ fontSize: 12 }}>
{props.description}
</div>
)}
{props.errorMessage &&
(
<div {...errorMessageProps} style={{ color: 'red', fontSize: 12 }}>
{props.errorMessage}
</div>
)}
</div>
);
}
<TextField label="Email" />
import {useTextField} from '@react-aria/textfield';
function TextField(props) {
let { label } = props;
let ref = React.useRef();
let {
labelProps,
inputProps,
descriptionProps,
errorMessageProps
} = useTextField(props, ref);
return (
<div
style={{
display: 'flex',
flexDirection: 'column',
width: 200
}}
>
<label {...labelProps}>{label}</label>
<input {...inputProps} ref={ref} />
{props.description &&
(
<div
{...descriptionProps}
style={{ fontSize: 12 }}
>
{props.description}
</div>
)}
{props.errorMessage &&
(
<div
{...errorMessageProps}
style={{ color: 'red', fontSize: 12 }}
>
{props.errorMessage}
</div>
)}
</div>
);
}
<TextField label="Email" />
import {useTextField} from '@react-aria/textfield';
function TextField(
props
) {
let { label } = props;
let ref = React
.useRef();
let {
labelProps,
inputProps,
descriptionProps,
errorMessageProps
} = useTextField(
props,
ref
);
return (
<div
style={{
display: 'flex',
flexDirection:
'column',
width: 200
}}
>
<label
{...labelProps}
>
{label}
</label>
<input
{...inputProps}
ref={ref}
/>
{props
.description &&
(
<div
{...descriptionProps}
style={{
fontSize:
12
}}
>
{props
.description}
</div>
)}
{props
.errorMessage &&
(
<div
{...errorMessageProps}
style={{
color:
'red',
fontSize:
12
}}
>
{props
.errorMessage}
</div>
)}
</div>
);
}
<TextField label="Email" />
Description#
<TextField
label="Email"
description="Enter an email for us to contact you about your order."
/>
<TextField
label="Email"
description="Enter an email for us to contact you about your order."
/>
<TextField
label="Email"
description="Enter an email for us to contact you about your order."
/>
Error message#
<TextField
label="Email"
errorMessage="Please enter a valid email address." />
<TextField
label="Email"
errorMessage="Please enter a valid email address." />
<TextField
label="Email"
errorMessage="Please enter a valid email address."
/>
Internationalization#
RTL#
In right-to-left languages, text fields should be mirrored. The label should be right aligned, along with the text in the text field. Ensure that your CSS accounts for this.