# React Native OTP Input

> React Native OTP input for verification codes and PINs: a box per character with a blinking caret, SMS code autofill on iOS, Android and the web, paste from a message, numeric or letters, secure dots, wrong-code errors. iOS, Material and web designs, zero native code.

# InputOTP

`InputOTP` is a React Native OTP input: the one-time code from a text message or an authenticator app, a box per character. It's the step after [`PhoneField`](./phone-field) in a phone sign-in.

One text field sits under the boxes, so everything a text field does works: the keyboard offers the code from the latest text message (iOS, Android and Safari), long-press pastes, and screen readers hear one field rather than six. The boxes look like the [design's](../guides/designs) text fields.

```tsx
import { InputOTP } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { Text, View } from 'react-native';
import { InputOTP } from 'patine-ui';

export default function Example() {
  const [code, setCode] = useState('');
  const [sent, setSent] = useState<string | null>(null);
  return (
    <View style={{ gap: 12 }}>
      <InputOTP value={code} onValueChange={setCode} onComplete={setSent} />
      <Text>{sent ? `Checking ${sent}…` : 'Enter the 6-digit code'}</Text>
    </View>
  );
}
```

Paste *Your code is 482-913* and the boxes fill with `482913`: the field keeps only the characters a code can have.

## Example: verify a phone number

The last step of a sign-up: the code goes to the number just entered, a wrong code clears the boxes with a message, and Resend unlocks after 30 seconds. The right code here is 246810.

```tsx live
import { useEffect, useState } from 'react';
import { Keyboard } from 'react-native';
import { Box, Button, InputOTP, Text, VStack } from 'patine-ui';

export default function Example() {
  const [code, setCode] = useState('');
  const [error, setError] = useState('');
  const [status, setStatus] = useState<'idle' | 'checking' | 'verified'>('idle');
  const [wait, setWait] = useState(30);
  useEffect(() => {
    if (!wait) return;
    const id = setTimeout(() => setWait(wait - 1), 1000);
    return () => clearTimeout(id);
  }, [wait]);
  const check = (full: string) => {
    setStatus('checking');
    Keyboard.dismiss();
    setTimeout(() => {
      if (full === '246810') return setStatus('verified');
      setStatus('idle');
      setError('That code didn’t match. Check the latest text and try again.');
      setCode('');
    }, 700);
  };
  if (status === 'verified')
    return (
      <Box border radius="lg" padding="lg" gap="xs" style={{ width: '100%', maxWidth: 380 }}>
        <Text weight="semibold">Number verified</Text>
        <Text color="textSecondary">We’ll text +31 6 12 34 56 78 for sign-in codes.</Text>
      </Box>
    );
  return (
    <Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 380 }}>
      <VStack gap="xs">
        <Text weight="semibold">Enter the code we sent</Text>
        <Text size="sm" color="textSecondary">A text with 6 digits went to +31 6 •• •• 56 78.</Text>
      </VStack>
      <InputOTP
        value={code}
        onValueChange={(next) => {
          setCode(next);
          setError('');
        }}
        onComplete={check}
        disabled={status === 'checking'}
        error={error}
        helperText={status === 'checking' ? 'Checking…' : 'The code works for 10 minutes.'}
        accessibilityLabel="Verification code"
      />
      <Button variant="ghost" disabled={wait > 0} onPress={() => setWait(30)}>
        {wait ? `Resend code in ${wait}s` : 'Resend code'}
      </Button>
    </Box>
  );
}
```

## Checking the code

`onComplete` fires once the user fills the last box, with the whole code: send it to your server there. `onValueChange` fires on every key, delete and paste, for a controlled field. Neither fires when you change `value` yourself.

For a wrong code, set `error` and `value` to `''`: the boxes turn red and empty, the message shows under them, and the field stays focused for another try. Clear `error` in `onValueChange`, so it goes once the user types again. `helperText` sits under the boxes until there's an error message, a good place for where the code was sent. To hide the keyboard while you check, call `Keyboard.dismiss()` in `onComplete`.

```tsx live
import { useState } from 'react';
import { Keyboard } from 'react-native';
import { InputOTP } from 'patine-ui';

const CORRECT = '1234';

export default function Example() {
  const [code, setCode] = useState('');
  const [error, setError] = useState('');
  return (
    <InputOTP
      length={4}
      value={code}
      onValueChange={(next) => {
        setCode(next);
        setError('');
      }}
      onComplete={(full) => {
        if (full === CORRECT) {
          Keyboard.dismiss();
          return;
        }
        setError('That code didn’t match. Try again.');
        setCode('');
      }}
      error={error}
      helperText="Sent to •••• 0123. Hint: 1234"
    />
  );
}
```

`error={true}` marks the boxes red without a message. Screen readers hear the error after the field's name, and the message is announced as it appears.

## Letters, and PINs

`inputMode="text"` takes letters and digits on the full keyboard, for codes like `A7K2Q9`. `secureTextEntry` shows each character as a dot, for a PIN.

```tsx live
import { View } from 'react-native';
import { InputOTP } from 'patine-ui';

export default function Example() {
  return (
    <View style={{ gap: 16 }}>
      <InputOTP inputMode="text" length={6} accessibilityLabel="Backup code" />
      <InputOTP secureTextEntry length={4} accessibilityLabel="PIN" />
    </View>
  );
}
```

## Designs

| iOS | Material | Web |
| --- | --- | --- |
| bordered boxes, the focused one in the primary colour | outlined boxes, the focused one with a 2dp primary outline | compact outlined boxes, the focused one with a focus ring |

Each box is up to 56 wide and as tall as the design's fields, sharing the row's width, so six fit on the narrowest phone. Restyle any part with `styles`.

## Accessibility

Screen readers see one text field, named by `accessibilityLabel`, with the code as its value and the `error` message as its hint; the boxes are hidden from them, and a new error is announced. Typing, deleting and pasting work as in any field, with a hardware keyboard too.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | The code so far (controlled). |
| `defaultValue` | `string` | `''` | Starting code when `value` isn't set. |
| `onValueChange` | `(code: string) => void` | — | As the user types, deletes or pastes. |
| `onComplete` | `(code: string) => void` | — | Once the user fills the last box. |
| `length` | `number` | `6` | How many characters the code has. |
| `inputMode` | `'numeric' \| 'text'` | `'numeric'` | Digits on a number pad, or letters and digits. |
| `secureTextEntry` | `boolean` | `false` | Dots instead of characters. |
| `autoFocus` | `boolean` | `false` | Focus the field when it mounts. |
| `disabled` | `boolean` | `false` | Dims the boxes and ignores typing. |
| `error` | `string \| boolean` | — | Shows the boxes as invalid, with the message under them when it's a string. See [Checking the code](#checking-the-code). |
| `helperText` | `string` | — | Shown under the boxes, replaced by the `error` message. |
| `accessibilityLabel` | `string` | `'Verification code'` | What screen readers call the field. |
| `theme` / `design` | | | See [Theming](../guides/theming) and [Designs](../guides/designs). |
| `style` | `StyleProp<ViewStyle>` | — | The field's container. |
| `styles` | `{ container, cell, focusedCell, filledCell, cellText, caret, helperText }` | — | [Slot styles](../guides/styling). `container` is the row of boxes; `helperText` the line under them. |
| `testID` | `string` | — | On the text input; box `i` gets `${testID}-cell-${i}`. |

## Related

- [PhoneField](./phone-field): the number to send the code to
- [Migrate from react-native-otp-entry](../resources/migration/otp-entry) or [react-native-confirmation-code-field](../resources/migration/confirmation-code-field)
