This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 55).

TextField

A SwiftUI TextField component for text input.

iOS

tvOS

GitHub

npm

Changelog

Expo UI TextField matches the official SwiftUI TextField API and supports single-line and multiline input, keyboard configuration, submit handling, and an imperative ref for programmatic control.

Installation

Terminal

- npx expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Basic text field

BasicTextFieldExample.tsx

import { useState } from 'react';
import { Host, TextField } from '@expo/ui/swift-ui';

export default function BasicTextFieldExample() {
  const [value, setValue] = useState('');

  return (
    <Host matchContents>
      <TextField placeholder="Username" onValueChange={setValue} />
    </Host>
  );
}

Multiline text field

Set axis="vertical" to allow the text field to expand vertically. Use the lineLimit modifier to control the visible line count. When using Host matchContents, add fixedSize({ horizontal: false, vertical: true }) so the text field accepts the parent's width while using its ideal height.

MultilineTextFieldExample.tsx

import { useState } from 'react';
import { Host, TextField } from '@expo/ui/swift-ui';
import { lineLimit, fixedSize } from '@expo/ui/swift-ui/modifiers';

export default function MultilineTextFieldExample() {
  const [value, setValue] = useState('');

  return (
    <Host matchContents>
      <TextField
        axis="vertical"
        placeholder="Tell us about yourself..."
        onValueChange={setValue}
        modifiers={[lineLimit(5), fixedSize({ horizontal: false, vertical: true })]}
      />
    </Host>
  );
}

Keyboard type

Use the keyboardType modifier to display a specific keyboard layout.

KeyboardTypeExample.tsx

import { useState } from 'react';
import { Host, TextField } from '@expo/ui/swift-ui';
import { keyboardType, autocorrectionDisabled } from '@expo/ui/swift-ui/modifiers';

export default function KeyboardTypeExample() {
  const [value, setValue] = useState('');

  return (
    <Host matchContents>
      <TextField
        placeholder="Email"
        onValueChange={setValue}
        modifiers={[keyboardType('email-address'), autocorrectionDisabled()]}
      />
    </Host>
  );
}

Submit handling

Use the submitLabel modifier to customize the return key and onSubmit to handle the submit action.

SubmitHandlingExample.tsx

import { useState } from 'react';
import { Host, TextField } from '@expo/ui/swift-ui';
import { submitLabel, onSubmit } from '@expo/ui/swift-ui/modifiers';

export default function SubmitHandlingExample() {
  const [value, setValue] = useState('');

  return (
    <Host matchContents>
      <TextField
        placeholder="Search..."
        onValueChange={setValue}
        modifiers={[submitLabel('search'), onSubmit(() => console.log('Submitted:', value))]}
      />
    </Host>
  );
}

Imperative ref

Use a ref to imperatively set text, focus, blur, or select text.

ImperativeRefExample.tsx

import { useRef } from 'react';
import { Host, TextField, TextFieldRef, Button, HStack, VStack } from '@expo/ui/swift-ui';
import { buttonStyle } from '@expo/ui/swift-ui/modifiers';

export default function ImperativeRefExample() {
  const ref = useRef<TextFieldRef>(null);

  return (
    <Host matchContents>
      <VStack>
        <TextField ref={ref} defaultValue="Select me!" placeholder="Imperative field" />
        <HStack spacing={12}>
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.focus()}
            label="Focus"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.blur()}
            label="Blur"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setText('SwiftUI rocks!')}
            label="Set Text"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setSelection(0, 7)}
            label="Select"
          />
        </HStack>
      </VStack>
    </Host>
  );
}

API

import { TextField } from '@expo/ui/swift-ui';

Component

`TextField`

iOS

tvOS

Type: React.Element<TextFieldProps>

Renders a SwiftUI TextField.

TextFieldProps

`autoFocus`

iOS

tvOS

Optional • Type: boolean • Default: false

If true, the text field will be focused automatically when mounted.

`axis`

iOS

tvOS

Optional • Literal type: string • Default: 'horizontal'

The axis along which the text field grows when content exceeds a single line.

'horizontal' — single line (default).
'vertical' — expands vertically for multiline content. Use lineLimit modifier to cap visible lines.

Acceptable values are: 'horizontal' | 'vertical'

`onFocusChange`

iOS

tvOS

Optional • Type: (focused: boolean) => void

A callback triggered when the field gains or loses focus.

`onSelectionChange`

iOS 18.0+ tvos 18.0+

Optional • Type:

({ start, end }: {
  end: number, 
  start: number
}) => void

A callback triggered when user selects text in the TextField.

`onTextChange`

iOS

tvOS

Optional • Type: (text: string) => void

A callback triggered when the text value changes.

If the callback is marked with the 'worklet' directive, it runs synchronously on the UI thread; otherwise it is delivered asynchronously as a regular JS event.

`placeholder`

iOS

tvOS

Optional • Type: string

A text that is displayed when the field is empty.

`ref`

iOS

tvOS

Optional • Type: Ref<TextFieldRef>

`text`

iOS

tvOS

Optional • Type: ObservableState<string>

An observable state that holds the current text. Create one with useNativeState('') or useNativeState('initial value'). If omitted, the field manages its own internal state.

Inherited Props

CommonViewModifierProps

Types

`TextFieldRef`

iOS

tvOS

Can be used for imperatively focusing and selecting text on the TextField component.

Property	Type	Description
blur	`() => Promise<void>`	-
focus	`() => Promise<void>`	-
setSelection	`(start: number, end: number) => Promise<void>`	Only for: iOS 18.0+ tvos 18.0+ Programmatically select text using start and end indices.
setText	`(newText: string) => Promise<void>`	-