TextField

A SwiftUI TextField component for text input.

iOS

tvOS

Included in Expo Go

Recommended version:

~56.0.26

For cross-platform usage, see the universal TextInput — it renders the appropriate native component per platform.

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

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

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

Usage

Uncontrolled text field

Bind a useNativeState observable to text. The field tracks the user's input on its own, and you read the current value from textState.value.

BasicTextFieldExample.tsx

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

export default function BasicTextFieldExample() {
  const textState = useNativeState('');

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

Controlled text field

Pass an onTextChange worklet to transform or validate input and write the result back to the useNativeState observable state. The example below uppercases the text as it is typed.

Note: Worklets require installing react-native-worklets.

ControlledTextFieldExample.tsx

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

export default function ControlledTextFieldExample() {
  const text = useNativeState('');

  const handleTextChange = useCallback(
    (value: string) => {
      'worklet';
      text.value = value.toUpperCase();
    },
    [text]
  );

  return (
    <Host matchContents>
      <TextField placeholder="Name" text={text} onTextChange={handleTextChange} />
    </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 { Host, TextField, useNativeState } from '@expo/ui/swift-ui';
import { lineLimit, fixedSize } from '@expo/ui/swift-ui/modifiers';

export default function MultilineTextFieldExample() {
  const textState = useNativeState('');

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

Keyboard type

Use the keyboardType modifier to display a specific keyboard layout.

KeyboardTypeExample.tsx

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

export default function KeyboardTypeExample() {
  const textState = useNativeState('');

  return (
    <Host matchContents>
      <TextField
        placeholder="Email"
        text={textState}
        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 { Host, TextField, useNativeState } from '@expo/ui/swift-ui';
import { submitLabel, onSubmit } from '@expo/ui/swift-ui/modifiers';

export default function SubmitHandlingExample() {
  const textState = useNativeState('');

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

Imperative ref

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

Note: setSelection requires iOS 18.0+ / tvOS 18.0+. The other ref methods work on all supported versions.

ImperativeRefExample.tsx

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

export default function ImperativeRefExample() {
  const ref = useRef<TextFieldRef>(null);
  const textState = useNativeState('Select me!');

  return (
    <Host matchContents>
      <VStack>
        <TextField ref={ref} text={textState} 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?.clear()}
            label="Clear"
          />
          <Button
            modifiers={[buttonStyle('bordered')]}
            onPress={() => ref.current?.setSelection(0, 7)}
            label="Select"
          />
        </HStack>
      </VStack>
    </Host>
  );
}

Worklet text masking

When onTextChange is marked with the 'worklet' directive, it runs synchronously on the UI thread, so writes to useNativeState observables inside the callback take effect before the next frame. There is no flicker between the typed text and the masked text. The example below masks a phone number as the user types and writes both text and selection from the worklet to keep the cursor at the end of the formatted value.

Note: Worklets require installing react-native-worklets. The selection prop requires iOS 18.0+ / tvOS 18.0+. On older versions the worklet can still update the text but cursor positioning is unavailable.

WorkletPhoneMaskExample.tsx

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

export default function WorkletPhoneMaskExample() {
  const phone = useNativeState('');
  const selection = useNativeState({ start: 0, end: 0 });

  const handleTextChange = useCallback(
    (v: string) => {
      'worklet';
      const digits = v.replace(/\D/g, '').slice(0, 10);
      let formatted = digits;
      if (digits.length > 6) {
        formatted = `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
      } else if (digits.length > 3) {
        formatted = `(${digits.slice(0, 3)}) ${digits.slice(3)}`;
      }
      if (formatted !== v) {
        phone.value = formatted;
        // Snaps to end for demo. Real masks need smarter cursor handling.
        selection.value = { start: formatted.length, end: formatted.length };
      }
    },
    [phone, selection]
  );

  return (
    <Host matchContents>
      <TextField
        text={phone}
        selection={selection}
        placeholder="(555) 123-4567"
        modifiers={[keyboardType('phone-pad')]}
        onTextChange={handleTextChange}
      />
    </Host>
  );
}

API

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

No API data file found, sorry!