- Components
- Inputs
- TextArea
TextArea
TextArea is a multiline text input.
Installation
Usage
Use a TextArea
to allow users to input a long string of free-form text.
Options
Prefix and suffix
To add additional context for the TextArea
, use the prefix
and suffix
props.
Label
A visual label can be provided for the TextArea
using the label prop or a hidden label using aria-label
prop.
Description
An errorMessage
can be supplied to a TextField, which will be displayed when the isInvalid
prop is set to true
.
Contextual help
A ContextualHelp
element may be placed next to the label to provide additional information or help about a text area.
Error message
An errorMessage
can be supplied to a TextArea, which will be displayed when the isInvalid
prop is set to true
.
Loading
Use the isLoading
prop to control the loading state of the TextArea.
Use the loaderPosition
prop to control the position of the loader.
Disabled
Use the isDisabled
prop to disable the TextArea.
ReadOnly
The isReadOnly
boolean prop makes the TextArea's text content immutable. Unlike isDisabled
, the text area remains focusable and the contents can still be copied.
Required
Use the isRequired
prop to mark the TextArea as required.
Use the necessityIndicator
prop to control the visual style of the required state.
Uncontrolled
Use the defaultValue
prop to set the default input value.
Controlled
Use the value
and onChange
props to control the value of the input.
mirrored text: Roses are red, violets are blue.
Composition
If you need to customize things further, you can drop down to the composition level.
API Reference
Prop | Type | Default | Description |
---|---|---|---|
prefix | ReactNode | - | A visual to display before the input. |
suffix | ReactNode | - | A visual to display after the input. |
loaderPosition | "prefix" | "suffix" | "suffix" | The loader position |
label | ReactNode | The content to display as the label. | |
description | ReactNode | A description for the field. Provides a hint such as specific requirements for what to choose. | |
errorMessage | ReactNode | (v: ValidationResult) => ReactNode | An error message for the field. | |
isLoading | boolean | - | Whether the TextField is in a pending state. |
isInvalid | boolean | - | Whether the value is invalid. |
isDisabled | boolean | - | Whether the input is disabled. |
isReadOnly | boolean | - | Whether the input can be selected but not changed by the user. |
isRequired | boolean | - | Whether user input is required on the input before form submission. |
validate | (value: string) => ValidationError | true | null | undefined | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead. |
autoFocus | boolean | - | Whether the element should receive focus on render. |
value | string | - | The current value (controlled). |
defaultValue | string | - | The default value (uncontrolled). |
autoComplete | string | - | Describes the type of autocomplete functionality the input should provide if any. |
maxLength | number | - | The maximum number of characters supported by the input. |
minLength | number | - | The minimum number of characters required by the input. |
pattern | string | - | Regex pattern that the value of the input must match to be valid. |
type | 'text' | 'search' | 'url' | 'tel' | 'email' | 'password' | string & {} | - | The type of input to render. |
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. |
name | string | - | The name of the input element, used when submitting an HTML form. |
validationBehavior | 'native' | 'aria' | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. |
children | ReactNode | (values: TextFieldRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNode | - | The children of the component. A function may be provided to alter the children based on component state. |
className | string | - | The CSS className for the element. |
style | CSSProperties | (values: TextFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties | - | The inline style for the element. A function may be provided to compute the style based on component state. |
Event | Type | Description |
---|---|---|
onFocus | (e: FocusEvent<Target>) => void | Handler that is called when the element receives focus. |
onBlur | (e: FocusEvent<Target>) => 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. |
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. |
onChange | (value: T) => void | Handler that is called when the value changes. |
onCopy | ClipboardEventHandler<HTMLInputElement> | Handler that is called when the user copies text. |
onCut | ClipboardEventHandler<HTMLInputElement> | Handler that is called when the user cuts text. |
onPaste | ClipboardEventHandler<HTMLInputElement> | Handler that is called when the user pastes text. |
onCompositionStart | CompositionEventHandler<HTMLInputElement> | Handler that is called when a text composition system starts a new text composition session. |
onCompositionEnd | CompositionEventHandler<HTMLInputElement> | Handler that is called when a text composition system completes or cancels the current text composition session. |
onCompositionUpdate | CompositionEventHandler<HTMLInputElement> | Handler that is called when a new character is received in the current text composition session. |
onSelect | ReactEventHandler<HTMLInputElement> | Handler that is called when text in the input is selected. |
onBeforeInput | FormEventHandler<HTMLInputElement> | Handler that is called when the input value is about to be modified. |
onInput | FormEventHandler<HTMLInputElement> | Handler that is called when the input value is modified. |
Data attribute | Description |
---|---|
[data-disabled] | Whether the text field is disabled. |
[data-invalid] | Whether the text field is invalid. |
[data-readonly] | Whether the text field is read only. |
[data-required] | Whether the text field is required. |
Last updated on 10/11/2024