This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
TextField
Jetpack Compose TextField components for native Material3 text input.
Expo UI provides two text field components that match the official Jetpack Compose TextField API: TextField (filled) and OutlinedTextField (outlined border). Both variants share the same props and support composable slot children for label, placeholder, icons, prefix, suffix, and supporting text.
| Type | Appearance | Purpose |
|---|---|---|
| Filled | Solid background with a bottom indicator line. | Default text input style following Material3 design. Use for most forms and input fields. |
| Outlined | Transparent background with a border outline. | Alternative style that provides a distinct visual boundary. Use when filled fields blend into the background. |
Installation
- npx expo install @expo/uiIf you are installing this in an existing React Native app, make sure to install expo in your project.
Usage
Basic text field
A filled text field is the default Material3 text input style.
import { useState } from 'react'; import { Host, TextField, Text } from '@expo/ui/jetpack-compose'; export default function BasicTextFieldExample() { const [value, setValue] = useState(''); return ( <Host matchContents> <TextField onValueChange={setValue}> <TextField.Label> <Text>Username</Text> </TextField.Label> </TextField> </Host> ); }
Outlined text field
Use OutlinedTextField for a text field with a border outline instead of a filled background.
import { useState } from 'react'; import { Host, OutlinedTextField, Text } from '@expo/ui/jetpack-compose'; export default function OutlinedTextFieldExample() { const [value, setValue] = useState(''); return ( <Host matchContents> <OutlinedTextField onValueChange={setValue}> <OutlinedTextField.Label> <Text>Email</Text> </OutlinedTextField.Label> <OutlinedTextField.Placeholder> <Text>you@example.com</Text> </OutlinedTextField.Placeholder> </OutlinedTextField> </Host> ); }
Slots
Both TextField and OutlinedTextField support 7 composable slots that match the Compose API: Label, Placeholder, LeadingIcon, TrailingIcon, Prefix, Suffix, and SupportingText.
import { useState } from 'react'; import { Host, TextField, Text } from '@expo/ui/jetpack-compose'; export default function TextFieldSlotsExample() { const [value, setValue] = useState(''); return ( <Host matchContents> <TextField onValueChange={setValue}> <TextField.Label> <Text>Price</Text> </TextField.Label> <TextField.Placeholder> <Text>0.00</Text> </TextField.Placeholder> <TextField.LeadingIcon> <Text>💰</Text> </TextField.LeadingIcon> <TextField.Prefix> <Text>$</Text> </TextField.Prefix> <TextField.Suffix> <Text>USD</Text> </TextField.Suffix> <TextField.SupportingText> <Text>Enter the amount</Text> </TextField.SupportingText> </TextField> </Host> ); }
Keyboard options
Use the keyboardOptions prop to configure the keyboard type, capitalization, auto-correct, and IME action.
import { useState } from 'react'; import { Host, TextField, Text } from '@expo/ui/jetpack-compose'; export default function KeyboardOptionsExample() { const [value, setValue] = useState(''); return ( <Host matchContents> <TextField onValueChange={setValue} singleLine keyboardOptions={{ keyboardType: 'email', capitalization: 'none', autoCorrectEnabled: false, imeAction: 'done', }}> <TextField.Label> <Text>Email</Text> </TextField.Label> </TextField> </Host> ); }
Keyboard actions
Use the keyboardActions prop to handle IME action button presses. The triggered callback depends on the imeAction set in keyboardOptions. Each callback receives the current text value.
import { useState } from 'react'; import { Host, TextField, Text } from '@expo/ui/jetpack-compose'; export default function KeyboardActionsExample() { const [value, setValue] = useState(''); const [submitted, setSubmitted] = useState(''); return ( <Host matchContents> <TextField onValueChange={setValue} singleLine keyboardOptions={{ imeAction: 'search' }} keyboardActions={{ onSearch: text => setSubmitted(text), }}> <TextField.Label> <Text>Search</Text> </TextField.Label> </TextField> </Host> ); }
Error state
Set isError to display the text field in an error state. Combine with SupportingText to show an error message.
import { useState } from 'react'; import { Host, OutlinedTextField, Text } from '@expo/ui/jetpack-compose'; export default function ErrorStateExample() { const [value, setValue] = useState(''); const hasError = value.length > 0 && !value.includes('@'); return ( <Host matchContents> <OutlinedTextField onValueChange={setValue} isError={hasError} singleLine> <OutlinedTextField.Label> <Text>Email</Text> </OutlinedTextField.Label> <OutlinedTextField.SupportingText> <Text>{hasError ? 'Please enter a valid email' : 'Required'}</Text> </OutlinedTextField.SupportingText> </OutlinedTextField> </Host> ); }
Imperative ref
Use a ref to imperatively set text, focus, or blur the text field.
import { useRef, useState } from 'react'; import { Host, TextField, TextFieldRef, Button, Row, Text, Column } from '@expo/ui/jetpack-compose'; import { padding } from '@expo/ui/jetpack-compose/modifiers'; export default function ImperativeRefExample() { const ref = useRef<TextFieldRef>(null); const [value, setValue] = useState(''); return ( <Host matchContents> <Column> <TextField ref={ref} onValueChange={setValue} singleLine> <TextField.Label> <Text>Name</Text> </TextField.Label> </TextField> <Row horizontalArrangement={{ spacedBy: 8 }} modifiers={[padding(8, 0, 0, 0)]}> <Button onClick={() => ref.current?.setText('Hello!')}> <Text>Set text</Text> </Button> <Button onClick={() => ref.current?.focus()}> <Text>Focus</Text> </Button> <Button onClick={() => ref.current?.blur()}> <Text>Blur</Text> </Button> </Row> </Column> </Host> ); }
API
import { TextField, OutlinedTextField } from '@expo/ui/jetpack-compose';
Components
Type: React.Element<BasicTextFieldProps>
A bare, unstyled Compose BasicTextField with no Material decoration.
Props for BasicTextField. Mirrors Compose's BasicTextField: a bare,
unstyled text field with no Material chrome (no container, indicator, or
built-in padding). Shares CommonTextFieldProperties with TextField and
OutlinedTextField; use BasicTextField.DecorationBox to add your own
decoration.
ColorValueColor of the text cursor. Maps to Compose's cursorBrush via
SolidColor(color). Defaults to the theme's primary color
(MaterialTheme.colorScheme.primary) so it stays visible in light and dark.
Type: React.Element<OutlinedTextFieldProps>
A Material3 OutlinedTextField with a transparent background and border outline.
Props shared by every Compose text field variant — TextField,
OutlinedTextField, and BasicTextField. The Material variants add their
own decoration props (isError, shape, colors, slot children);
BasicTextField adds cursorColor.
TextFieldColorsShapeJSXElementShape used for the field's container outline/fill. Use the helpers from
Shape (for example, <Shape.Pill /> or <Shape.RoundedCorner cornerRadii={...} />).
Defaults to the Material OutlinedTextFieldDefaults.shape/TextFieldDefaults.shape.
Type: React.Element<TextFieldProps>
A Material3 TextField.
Props shared by every Compose text field variant — TextField,
OutlinedTextField, and BasicTextField. The Material variants add their
own decoration props (isError, shape, colors, slot children);
BasicTextField adds cursorColor.
TextFieldColorsShapeJSXElementShape used for the field's container outline/fill. Use the helpers from
Shape (for example, <Shape.Pill /> or <Shape.RoundedCorner cornerRadii={...} />).
Defaults to the Material OutlinedTextFieldDefaults.shape/TextFieldDefaults.shape.
Types
Type: TextFieldRef
Imperative methods for BasicTextField. Identical to TextFieldRef.
Props shared by every Compose text field variant — TextField,
OutlinedTextField, and BasicTextField. The Material variants add their
own decoration props (isError, shape, colors, slot children);
BasicTextField adds cursorColor.
| Property | Type | Description |
|---|---|---|
| autoFocus(optional) | boolean | If true, the text field will be focused automatically when mounted. Default: false |
| children(optional) | ReactNode | Slot children that configure the field's decoration. |
| enabled(optional) | boolean | Default: true |
| keyboardActions(optional) | TextFieldKeyboardActions | - |
| keyboardOptions(optional) | TextFieldKeyboardOptions | - |
| maxLength(optional) | number | Maximum number of characters allowed. Truncates natively as the user types. |
| maxLines(optional) | number | - |
| minLines(optional) | number | - |
| modifiers(optional) | ModifierConfig[] | - |
| onFocusChanged(optional) | (focused: boolean) => void | A callback triggered when the field gains or loses focus. |
| onSelectionChange(optional) | (selection: {
end: number,
start: number
}) => void | Called when the selection range changes. |
| onValueChange(optional) | (value: string) => void | Fires whenever the text value changes. If marked with the |
| readOnly(optional) | boolean | Default: false |
| ref(optional) | Ref<TextFieldRef> | - |
| selection(optional) | ObservableState<{
end: number,
start: number
}> | Observable state holding the current selection range. Create with
|
| singleLine(optional) | boolean | Default: false |
| textSelectionColors(optional) | {
backgroundColor: ColorValue,
handleColor: ColorValue
} | Selection-related colors. Maps to Compose's |
| textStyle(optional) | TextFieldTextStyle | Text styling for the field's content. Maps to Compose's |
| value(optional) | ObservableState<string> | An observable state that holds the current text value. Create one with
|
| visualTransformation(optional) | 'password' | 'none' | Display-time text transformation. |
Observable state shared between JavaScript and native views (Jetpack Compose on Android and SwiftUI on iOS).
Type: SharedObject extended by:
| Property | Type | Description |
|---|---|---|
| onChange | [listener] | null | A single listener invoked on the native UI runtime whenever the value changes
(after iOS The callback must be a worklet so it can run synchronously on the UI thread.
Attach it inside Example
|
| value | T | The current value. Writes from a UI worklet are synchronous and immediately readable. Writes from the JS thread are scheduled to the UI thread asynchronously, the new value is not readable until the update has been applied. Prefer writing from a worklet when you need synchronous updates |
| get | () => T | Reads the current value. A React Compiler compliant alternative to reading |
| set | (value: T) => void | Writes a new value. A React Compiler-compliant alternative to assigning |
Literal Type: string
Acceptable values are: 'none' | 'characters' | 'words' | 'sentences'
Colors for TextField and OutlinedTextField.
Maps to TextFieldColors in Compose, shared by both variants.
| Property | Type | Description |
|---|---|---|
| cursorColor(optional) | ColorValue | - |
| disabledContainerColor(optional) | ColorValue | - |
| disabledIndicatorColor(optional) | ColorValue | - |
| disabledLabelColor(optional) | ColorValue | - |
| disabledLeadingIconColor(optional) | ColorValue | - |
| disabledPlaceholderColor(optional) | ColorValue | - |
| disabledPrefixColor(optional) | ColorValue | - |
| disabledSuffixColor(optional) | ColorValue | - |
| disabledSupportingTextColor(optional) | ColorValue | - |
| disabledTextColor(optional) | ColorValue | - |
| disabledTrailingIconColor(optional) | ColorValue | - |
| errorContainerColor(optional) | ColorValue | - |
| errorCursorColor(optional) | ColorValue | - |
| errorIndicatorColor(optional) | ColorValue | - |
| errorLabelColor(optional) | ColorValue | - |
| errorLeadingIconColor(optional) | ColorValue | - |
| errorPlaceholderColor(optional) | ColorValue | - |
| errorPrefixColor(optional) | ColorValue | - |
| errorSuffixColor(optional) | ColorValue | - |
| errorSupportingTextColor(optional) | ColorValue | - |
| errorTextColor(optional) | ColorValue | - |
| errorTrailingIconColor(optional) | ColorValue | - |
| focusedContainerColor(optional) | ColorValue | - |
| focusedIndicatorColor(optional) | ColorValue | - |
| focusedLabelColor(optional) | ColorValue | - |
| focusedLeadingIconColor(optional) | ColorValue | - |
| focusedPlaceholderColor(optional) | ColorValue | - |
| focusedPrefixColor(optional) | ColorValue | - |
| focusedSuffixColor(optional) | ColorValue | - |
| focusedSupportingTextColor(optional) | ColorValue | - |
| focusedTextColor(optional) | ColorValue | - |
| focusedTrailingIconColor(optional) | ColorValue | - |
| unfocusedContainerColor(optional) | ColorValue | - |
| unfocusedIndicatorColor(optional) | ColorValue | - |
| unfocusedLabelColor(optional) | ColorValue | - |
| unfocusedLeadingIconColor(optional) | ColorValue | - |
| unfocusedPlaceholderColor(optional) | ColorValue | - |
| unfocusedPrefixColor(optional) | ColorValue | - |
| unfocusedSuffixColor(optional) | ColorValue | - |
| unfocusedSupportingTextColor(optional) | ColorValue | - |
| unfocusedTextColor(optional) | ColorValue | - |
| unfocusedTrailingIconColor(optional) | ColorValue | - |
Literal Type: string
Acceptable values are: 'default' | 'none' | 'go' | 'search' | 'send' | 'previous' | 'next' | 'done'
Keyboard actions matching Compose KeyboardActions.
The triggered callback depends on the imeAction in keyboardOptions.
| Property | Type | Description |
|---|---|---|
| onDone(optional) | (value: string) => void | - |
| onGo(optional) | (value: string) => void | - |
| onNext(optional) | (value: string) => void | - |
| onPrevious(optional) | (value: string) => void | - |
| onSearch(optional) | (value: string) => void | - |
| onSend(optional) | (value: string) => void | - |
Keyboard options matching Compose KeyboardOptions.
| Property | Type | Description |
|---|---|---|
| autoCorrectEnabled(optional) | boolean | Default: true |
| capitalization(optional) | TextFieldCapitalization | Default: 'none' |
| imeAction(optional) | TextFieldImeAction | Default: 'default' |
| keyboardType(optional) | TextFieldKeyboardType | Default: 'text' |
Literal Type: string
Acceptable values are: 'text' | 'number' | 'email' | 'phone' | 'decimal' | 'password' | 'ascii' | 'uri' | 'numberPassword'
Can be used for imperatively focusing and setting text/selection on the
TextField, OutlinedTextField, and BasicTextField components.
Text styling for a text field's content. Maps to Compose's TextStyle.
Shared by TextField, OutlinedTextField, and BasicTextField.
| Property | Type | Description |
|---|---|---|
| color(optional) | ColorValue | - |
| fontFamily(optional) | string | - |
| fontSize(optional) | number | - |
| fontWeight(optional) | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | 'normal' | 'bold' | - |
| letterSpacing(optional) | number | - |
| lineHeight(optional) | number | - |
| textAlign(optional) | 'left' | 'right' | 'center' | 'justify' | - |