TextInput

The TextInput component allows users to input strings.

Basic usage

You can use the defaultValue prop to set the initial value, and access this from value on the component state.
tsx
Copied
1
<TextInput id="textInput" label="Input your name" defaultValue="John Smith" />
2
<Text>Your name is {textInputState.value}</Text>

Focusing

You can focus on the text input by calling the focus function from the component state.
tsx
Copied
1
<Button onClick={() => textInputState.focus()}>Focus on input</Button>
2
<TextInput id="textInput" label="Input your name" defaultValue="John Smith" />
3
<Text>Your name is {textInputState.value}</Text>

Disabling

You can disable the text input by setting the defaultDisabled prop on the TextInput component, or by calling setDisabled from the component state.
tsx
Copied
1
<Button onClick={() => textInputState.setDisabled(!textInputState.disabled)}>
2
Toggle disabled
3
</Button>
4
<TextInput id="textInput" label="Input your name" defaultValue="John Smith" defaultDisabled />
5
<Text>Your name is {textInputState.value}</Text>

Component API

defaultDisabled
optional
boolean

The input's disabled state on initial render.

defaultValue
optional
string

The input value on initial render.

description
optional
React.ReactNode

Description displayed below the input.

disabled
optional
boolean

Disables the input. Prefer to use defaultDisabled and component state.

error
optional
React.ReactNode

Error text displayed below the input.

grow
optional
boolean

If true, the element will grow to fill available space.

This prop works only if the element is a direct child of a Stack.

height
optional
Default
auto
SizingToken | "{number}px"
Defines the height of the component. See SizingToken docs for more details.
icon
optional
React.ReactNode

Adds an icon to the left of the input.

id
optional
string

The ID referenced by the global component state.

label
optional
React.ReactNode

Label displayed above the input.

onChange
optional
(value: string) => void

Callback when input changes when using as a controlled component. Prefer using the global component state.

placeholder
optional
string

Hint text displayed when the input is empty.

radius
optional
"xs" | "sm" | "md" | "lg" | "xl"

The input's border radius.

required
optional
Default
false
boolean

Adds red asterisk on the right side of label and sets required on input element

size
optional
"xs" | "sm" | "md" | "lg" | "xl"

Input size.

type
optional
"text" | "password"

Type of text input. Set to password to hide the inputted text while typing.

validate
optional
((value: string) => string | undefined) | Array<(value: string) => string | undefined>

A single function or an array of functions that validate the input value.

value
optional
string

The value of the input when using as a controlled component. Prefer using defaultValue and the global component state.

variant
optional
"unstyled" | "default"

Input appearance.

width
optional
Default
auto
SizingToken | "{number}px"
Defines the width of the component. See SizingToken docs for more details.

State API

disabled
optional
boolean

Whether the text input is disabled

setDisabled
optional
(disabled?: boolean) => void

Sets the disabled value of the text input. If the disabled value is not provided, the text input will be disabled

setValue
optional
(value: string) => void

Sets the value of the text input

value
optional
string

The string currently in the text input