React Native OTPKit

https://github.com/sectiontn/react-native-otpkit
Admin
React Native OTPKit is a customizable one-time code (OTP) field for React Native apps on Android,...
Tokens:54,817
Snippets:310
Trust Score:8.8
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Run the example app

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/CONTRIBUTING.md

Start Metro and build/launch the example app on Android, iOS, or web. The first Android/iOS run creates native folders with expo prebuild.

```sh
yarn example start
yarn example android
yarn example ios
yarn example web
```

--------------------------------

### Install Playwright browsers and run web e2e

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/CONTRIBUTING.md

Install Chromium and WebKit browsers once, then export the example and run e2e tests on web targets.

```sh
npx playwright-core install chromium webkit
yarn e2e:web:build
yarn e2e --target web
yarn e2e --target web-webkit
```

--------------------------------

### Direct Consumption Example

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/native-module.md

Shows how to use the NativeOTPKit module directly, checking availability and starting a consent session. This is not part of the public API; the recommended approach is to use useSmsCode and getAppHash.

```tsx
import NativeOTPKit from 'react-native-otpkit/src/specs/NativeOTPKit';

if (NativeOTPKit?.isAvailable()) {
  const message = await NativeOTPKit.startConsent(null); // user taps Allow
}
```

--------------------------------

### useResendTimer(seconds, { autoStart })

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Counts down for a resend button and returns an object with remaining, canResend, and restart. It starts on mount unless autoStart is false.

```APIDOC
## useResendTimer(seconds, { autoStart })

### Description
Counts down for a resend button and returns `{ remaining, canResend, restart }`. It starts on mount unless `autoStart` is `false`. Time in the background counts.

### Parameters
- **seconds** (number) - Required - The countdown duration in seconds.
- **autoStart** (boolean) - Optional - Whether to start the timer on mount. Defaults to true.

### Returns
- **remaining** (number) - The remaining seconds.
- **canResend** (boolean) - Whether the resend button can be pressed.
- **restart** (function) - Restarts the countdown.
```

--------------------------------

### Manual start with autoStart false

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/useResendTimer.md

Creates a timer with autoStart: false so the button starts enabled ('Send code') and only becomes disabled after the user taps it, which calls sendCode() and timer.restart().

```tsx
const timer = useResendTimer(60, { autoStart: false });

<Button
  title={timer.canResend ? 'Send code' : `Resend in ${timer.remaining}s`}
  disabled={!timer.canResend}
  onPress={() => {
    sendCode();
    timer.restart();
  }}
/>;
```

--------------------------------

### Install dependencies with Yarn

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/CONTRIBUTING.md

Install all workspace dependencies from the repository root. The repository is a Yarn workspace; npm won't install it without changes.

```sh
yarn
```

--------------------------------

### Run Kotlin unit tests

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/CONTRIBUTING.md

Run Kotlin unit tests from the prebuilt example. Requires expo prebuild and Gradle.

```sh
cd example
npx expo prebuild --platform android
cd android
./gradlew :react-native-otpkit:testDebugUnitTest
```

--------------------------------

### Constants and Types

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

Constant objects and their corresponding TypeScript types for configuring OTP fields and interpreting statuses.

```APIDOC
## Constants and Types

### Description
Constant objects and their corresponding TypeScript types for configuring OTP fields and interpreting statuses.

### Constants
- **CodeType** - Values: 'numeric', 'alpha', 'alphanumeric' (each value is its key in lowercase).
- **SmsMode** - Values: 'consent', 'retriever' (each value is its key in lowercase).
- **Variant** - Values: 'outlined', 'filled', etc. (each value is its key in lowercase).
- **OTPStatus** - Values: 'idle', 'verifying', 'success', 'error' (each value is its key in lowercase).
- **SmsStatus** - Values: 'idle', 'listening', 'received', 'denied', 'timeout' (each value is its key in lowercase).

### Types
Each constant name is also a TypeScript type (e.g., `SmsMode`, `OTPStatus`).
```

--------------------------------

### Install react-native-otpkit with npm, Yarn, or Bun

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Install the package using your preferred package manager. Requires React Native 0.86+ (Expo SDK 57+), iOS 15.1+, Android 7.0+ (API 24), and react-native-web 0.21+ for web. For SMS reading on Expo, a development build is required.

```sh
# npm
npm install react-native-otpkit
# Yarn
yarn add react-native-otpkit
# Bun
bun add react-native-otpkit
```

--------------------------------

### Use OTPField with SMS consent and resend timer

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Example component that uses OTPField with SmsMode.Consent and useResendTimer to handle OTP input and resend functionality. The timer starts at 30 seconds, disables the button until canResend is true, and restarts on press while also triggering listenForSms on the field ref.

```tsx
import { useRef } from 'react';
import { Button, View } from 'react-native';
import { OTPField, type OTPFieldRef, SmsMode, useResendTimer } from 'react-native-otpkit';

export function CodeStep(props: { verify: (code: string) => Promise<void>; resend: () => void }) {
  const field = useRef<OTPFieldRef>(null);
  const timer = useResendTimer(30);

  return (
    <View style={{ gap: 16, padding: 24 }}>
      <OTPField ref={field} sms={SmsMode.Consent} onComplete={props.verify} />
      <Button
        title={timer.canResend ? 'Resend code' : `Resend in ${timer.remaining}s`}
        disabled={!timer.canResend}
        onPress={() => {
          props.resend();
          timer.restart();
          field.current?.listenForSms();
        }}
      />
    </View>
  );
}
```

--------------------------------

### Example SMS message with hash

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/guides/sms.md

Example message format for retriever mode: the code followed by the app hash on the last line.

```text
Your code is 123456

FA+9qCX9VSu
```

--------------------------------

### useResendTimer

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

Hook to manage a resend countdown timer. Returns the remaining seconds, whether resend is allowed, and a restart function. The timer counts against the clock, so time in the background counts.

```APIDOC
## useResendTimer

### Description
Hook to manage a resend countdown timer. Returns the remaining seconds, whether resend is allowed, and a restart function. The timer counts against the clock, so time in the background counts.

### Parameters
- `seconds` (number) - Required - The number of seconds for the countdown.
- `autoStart` (boolean) - Optional - Whether the timer starts automatically.

### Returns
- `remaining` (number) - The remaining seconds.
- `canResend` (boolean) - Whether resend is allowed.
- `restart` (function) - Restarts the timer.
```

--------------------------------

### useResendTimer hook

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

A React hook that provides a countdown timer for resend actions. It exposes `canResend`, `remaining`, and `restart` to manage the resend cooldown.

```APIDOC
## useResendTimer

### Description
A React hook that provides a countdown timer for resend actions. It exposes `canResend`, `remaining`, and `restart` to manage the resend cooldown.

### Parameters
- **seconds** (number) - Required - Duration of the countdown in seconds.

### Returns
- **canResend** (boolean) - Whether the resend action is allowed (timer has finished).
- **remaining** (number) - Seconds remaining until resend is allowed.
- **restart** (function) - Restarts the countdown.

### Example
```tsx
const timer = useResendTimer(30);
```
```

--------------------------------

### Basic headless OTP field with useOTPField

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/useOTPField.md

Headless field example from example/src/HeadlessScreen.tsx. Renders cells and a hidden TextInput. Requires length: 4 and styles for the input.

```tsx
import { StyleSheet, Text, TextInput, View } from 'react-native';
import { useOTPField } from 'react-native-otpkit';

export function CodeField() {
  const field = useOTPField({ length: 4 });

  return (
    <View style={{ height: 80 }}>
      <View style={{ flexDirection: 'row', gap: 8, pointerEvents: 'none' }}>
        {field.cells.map((cell) => (
          <View
            key={cell.index}
            style={{ borderBottomWidth: 3, borderColor: cell.isActive ? '#2563EB' : '#D4D4D4' }}
          >
            <Text style={{ fontSize: 40 }}>{cell.char}</Text>
          </View>
        ))}
      </View>
      <TextInput
        {...field.inputProps}
        accessibilityLabel="Verification code"
        style={[StyleSheet.absoluteFill, styles.input]}
      />
    </View>
  );
}

const styles = StyleSheet.create({ input: { opacity: 0.011, color: 'transparent' } });
```

--------------------------------

### NativeOTPKit Spec Interface

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/native-module.md

Defines the TypeScript interface for the OTPKit TurboModule, including methods for checking availability, starting consent and retriever sessions, stopping, and getting the app hash. The default export retrieves the module via TurboModuleRegistry.

```tsx
export interface Spec extends TurboModule {
  isAvailable(): boolean;
  startConsent(sender: string | null): Promise<string>;
  startRetriever(): Promise<string>;
  stop(): void;
  getAppHash(): Promise<string>;
}

export default TurboModuleRegistry.get<Spec>('OTPKit');
```

--------------------------------

### getAppHash function

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

Returns the SMS Retriever app hash for the current build. Useful for configuring the server to send the correct hash in SMS messages.

```APIDOC
## getAppHash

### Description
Returns the SMS Retriever app hash for the current build. Useful for configuring the server to send the correct hash in SMS messages.

### Returns
- **Promise<string | null>** - The app hash string, or `null` on iOS and web.

### Example
```tsx
const hash = await getAppHash();
```
```

--------------------------------

### Usage example with imports and interchangeable constants

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/constants.md

Shows importing all constants and using them interchangeably with string literals in props and type annotations. Constants and strings are interchangeable, e.g., SmsMode.Consent equals 'consent'.

```tsx
import { CodeType, OTPStatus, SmsMode, SmsStatus, Variant } from 'react-native-otpkit';

// Constants and strings are interchangeable:
<OTPField sms={SmsMode.Consent} variant={Variant.Underline} type={CodeType.Numeric} />;

// As a type:
const smsStatus: SmsStatus = 'received';
const status: OTPStatus = OTPStatus.Success;
const mode: SmsMode = 'retriever';
```

--------------------------------

### useSmsCode

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

Hook to listen for SMS codes. Returns an object with the current code, message, status, and control functions. The status can be 'idle', 'listening', 'received', 'timeout', 'denied', or 'unavailable'.

```APIDOC
## useSmsCode

### Description
Hook to listen for SMS codes. Returns an object with the current code, message, status, and control functions. The status can be 'idle', 'listening', 'received', 'timeout', 'denied', or 'unavailable'.

### Parameters
- `mode` (string) - Optional - The mode of SMS reading.
- `length` (number) - Optional - The expected length of the code.
- `type` (string) - Optional - The type of code.
- `sender` (string) - Optional - The sender of the SMS.
- `extract` (function) - Optional - Custom function to extract the code from the message. Replaces the default code search (not on web).
- `enabled` (boolean) - Optional - If `false`, waits for `start()` to begin listening.

### Returns
- `code` (string) - The extracted code.
- `message` (string) - The full SMS message.
- `status` (string) - Current status: 'idle', 'listening', 'received', 'timeout', 'denied', or 'unavailable'.
- `start` (function) - Starts listening.
- `stop` (function) - Stops listening.
```

--------------------------------

### Basic OTPField with SMS consent and verifying flow

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/OTPField.md

Use this example to create a basic OTP field with SMS consent and a verifying flow. The `onComplete` callback receives the entered code and should return a promise that rejects on a wrong code. The `ref` is typed as `OTPFieldRef` and can be used to call methods like `focus`, `blur`, `clear`, `setValue`, and `listenForSms`.

```tsx
import { useRef } from 'react';
import { OTPField, type OTPFieldRef, SmsMode } from 'react-native-otpkit';

const field = useRef<OTPFieldRef>(null);

const verify = (code: string) => sendCode(code); // returns a promise, rejects on a wrong code

<OTPField
  ref={field}
  sms={SmsMode.Consent}
  length={6}
  onComplete={verify}
  onBlur={() => console.log('blurred')}
/>;
```

--------------------------------

### listenForSms

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/OTPField.md

Starts listening for the SMS again (e.g. after a resend). Does nothing unless sms is set and the field is not disabled.

```APIDOC
## listenForSms

### Description
Starts listening for the SMS again (e.g. after a resend). Does nothing unless sms is set and the field is not disabled.

### Method
ref method

### Signature
`() => void`

### Parameters
None

### Returns
void
```

--------------------------------

### Custom cell style with state function

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

Use this pattern to style built-in cells based on their state. The cell provides isActive, isFilled, isDisabled, and status; the placeholder shows where isFilled is false. No focusedCellStyle, errorCellStyle, or placeholderStyle props exist.

```javascript
cellStyle={({ isActive, status }) => [isActive && styles.active, status === 'error' && styles.error]}
```

--------------------------------

### Display app hash in a React Native component (TypeScript)

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/getAppHash.md

Example component that fetches and displays the app hash, showing 'unavailable' if null or on error. Uses useEffect with cleanup to avoid state updates after unmount.

```tsx
import { useEffect, useState } from 'react';
import { Text } from 'react-native';
import { getAppHash } from 'react-native-otpkit';

export function AppHashRow() {
  const [hash, setHash] = useState<string | null | undefined>(undefined);

  useEffect(() => {
    let active = true;
    getAppHash().then(
      (appHash) => active && setHash(appHash),
      () => active && setHash(null),
    );
    return () => {
      active = false;
    };
  }, []);

  return <Text selectable>{hash ?? 'unavailable'}</Text>;
}
```

--------------------------------

### OTPField with error handling and custom styling

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/OTPField.md

Use this example to customize the OTP field's appearance and handle errors. The `cellStyle` function receives `isActive` and `status` to apply conditional styles. On a rejected `onComplete` promise, the field shakes, announces "Incorrect code", clears after 600 ms, and refocuses unless `clearOnError={false}` is set.

```tsx
<OTPField
  groups={[3, 3]}
  variant="underline"
  placeholder="•"
  cellStyle={({ isActive, status }) => [
    isActive && { borderColor: '#FF6F61' },
    status === 'error' && { backgroundColor: '#FEF2F2' },
  ]}
  onComplete={async (code) => {
    try {
      await verify(code);
    } catch {
      // On reject the field shakes, announces "Incorrect code",
      // clears after 600 ms and refocuses (unless clearOnError={false}).
    }
  }}
/>
```

--------------------------------

### OTPField

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

A component for OTP input. It provides a hidden input with autofill support and customizable cells. Style props only apply to built-in cells; with `renderCell`, they are ignored.

```APIDOC
## OTPField

### Description
A component for OTP input. It provides a hidden input with autofill support and customizable cells. Style props only apply to built-in cells; with `renderCell`, they are ignored.

### Props
- `variant` (string) - Optional - The variant of the field.
- `cellStyle` (style or function) - Optional - Style for cells. Can be a style object or a function of the cell state (e.g., `({ isActive, status }) => [...]`).
- `textStyle` (style or function) - Optional - Style for text in cells. Can be a style object or a function of the cell state.
- `placeholder` (string) - Optional - Placeholder character shown where `isFilled` is `false`.
- `caretStyle` (style) - Optional - Style for the caret.
- `renderCell` (function) - Optional - Custom render function for cells. When provided, `variant`, `cellStyle`, `textStyle`, `placeholder`, and `caretStyle` are ignored.
- `secure` (boolean) - Optional - If `true`, masks the cells (not the input).
- `autoFocus` (boolean) - Optional - Defaults to `true`. On Android, waits 300 ms before focusing.
- `textInputProps` (object) - Optional - Additional props for the hidden TextInput. Cannot override `value`, `onChangeText`, ref, `testID`, or `accessibilityLabel`.
- `testID` (string) - Optional - Test ID for the input. The input gets `<testID>-input` and each cell `<testID>-cell-<index>`.
- `accessibilityLabel` (string) - Optional - Accessibility label for the input.

### Cell State
- `isActive` (boolean) - Whether the cell is active.
- `isFilled` (boolean) - Whether the cell is filled.
- `isDisabled` (boolean) - Whether the cell is disabled.
- `status` (string) - The status of the cell (e.g., 'error').
- `char` (string) - The character in the cell (a dot when `secure` is on).
```

--------------------------------

### Style cells by state with cellStyle function

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/guides/styling.md

Pass a function to `cellStyle` to style each cell from its state. This example colors the focused cell and cells of a wrong code.

```tsx
<OTPField
  cellStyle={({ isActive, status }) => [
    isActive && { borderColor: '#FF6F61' },
    status === 'error' && { backgroundColor: '#FEF2F2' },
  ]}
/>
```

--------------------------------

### OTPField component

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

A React Native component for entering one-time passwords with support for SMS autofill, controlled/uncontrolled modes, and customizable validation. It handles focus, paste, and status transitions automatically.

```APIDOC
## OTPField

### Description
A React Native component for entering one-time passwords with support for SMS autofill, controlled/uncontrolled modes, and customizable validation. It handles focus, paste, and status transitions automatically.

### Props
- **value** (string) - Optional - Controlled value; when provided, the field is controlled.
- **onChange** (function) - Optional - Called on every change with the sanitized code; never debounced.
- **defaultValue** (string) - Optional - Initial value for uncontrolled mode.
- **onComplete** (function) - Optional - Called with the complete code when a new complete code appears (from typing, paste, autofill, SMS, setValue, or controlled value). Should return a promise; while pending, status is 'verifying' and input is ignored.
- **type** (string | RegExp) - Optional - 'numeric' (default), 'alpha', 'alphanumeric', or a RegExp tested on one character at a time.
- **length** (number) - Optional - Maximum code length; default is 6.
- **sms** (boolean | object) - Optional - Enables SMS listening; defaults to false. Can be `true`, `SmsMode.Consent`, `SmsMode.Retriever`, or `{ mode: SmsMode, sender?: string }`.
- **status** (string) - Optional - Overrides internal status; when set, the field only styles itself and never clears on its own.
- **clearOnError** (boolean) - Optional - If false, does not clear cells on error; default true.
- **blurOnComplete** (boolean) - Optional - If true, blurs the field when a code completes and status is idle.
- **disabled** (boolean) - Optional - Disables the field and SMS listening.
- **transform** (function) - Optional - Runs on all incoming text before filtering.

### Ref Methods
- **listenForSms()** - Starts listening for an SMS; does nothing if sms is off or field is disabled.

### Example
```tsx
<OTPField ref={field} sms={SmsMode.Consent} onComplete={verify} />
```
```

--------------------------------

### useSmsCode({ mode, length, type, sender, extract, enabled })

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Listens for an SMS without a field and returns an object with code, message, status, start, and stop. The `extract` function replaces the default code search, except on the web where the browser hands over the code.

```APIDOC
## useSmsCode({ mode, length, type, sender, extract, enabled })

### Description
Listens for an SMS without a field and returns `{ code, message, status, start, stop }`. `extract(message)` replaces the default code search, except on the web, where the browser hands over the code. With `enabled: false`, it waits for `start()`.

### Parameters
- **mode** (SmsMode) - Required - The SMS listening mode (Consent or Retriever).
- **length** (number) - Required - The expected length of the OTP code.
- **type** (CodeType) - Required - The type of code (Numeric, Alpha, Alphanumeric).
- **sender** (string) - Optional - The sender identifier to filter messages.
- **extract** (function) - Optional - Custom function to extract the code from a message.
- **enabled** (boolean) - Optional - Whether to start listening immediately. Defaults to true.

### Returns
- **code** (string|null) - The extracted code, or null if not found.
- **message** (string) - The full message text (on web, the code).
- **status** (SmsStatus) - The current listening status.
- **start** (function) - Starts listening.
- **stop** (function) - Stops listening.
```

--------------------------------

### Custom extraction and manual start

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/useSmsCode.md

Configure useSmsCode with enabled: false and a custom extract function that parses the message for a 6-digit code. Call sms.start() later and watch sms.status for 'listening', 'received', 'timeout', 'denied', or 'unavailable'.

```tsx
const sms = useSmsCode({
  mode: 'consent',
  enabled: false,
  extract: (message) => message.match(/code: (\d{6})/)?.[1] ?? null,
});

// Later, with error handling around the statuses:
sms.start();
// watch sms.status: 'listening' -> 'received' (sms.code) | 'timeout' | 'denied' | 'unavailable'
```

--------------------------------

### Build and run iOS e2e tests

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/CONTRIBUTING.md

Prepare the iOS runner, build the app, and run e2e tests. Boot the simulator without a window to avoid paste test failures.

```sh
npx agent-device prepare ios-runner --platform ios --timeout 900000
yarn e2e:ios:build
OTPKIT_APP_PATH=example/ios/build/Build/Products/Release-iphonesimulator/OTPKitExample.app yarn e2e --target ios
```

--------------------------------

### Build and run Android e2e tests

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/CONTRIBUTING.md

Build the Android release APK and run e2e tests against it. The build targets arm64 emulators.

```sh
yarn e2e:android:build
OTPKIT_APP_PATH=example/android/app/build/outputs/apk/release/app-release.apk yarn e2e --target android
```

--------------------------------

### useSmsCode with custom extract

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/guides/sms.md

Pass an extract function to find the code yourself, for example when the message contains multiple numbers.

```tsx
const sms = useSmsCode({
  mode: 'consent',
  extract: (message) => message.match(/code: (\d{6})/)?.[1] ?? null,
});
```

--------------------------------

### useOTPField(options)

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Holds the field logic for an input and cells you draw yourself. It returns an object with value, status, isFocused, cells, inputProps, focus, blur, clear, and setValue.

```APIDOC
## useOTPField(options)

### Description
Holds the field logic for an input and cells you draw yourself. Its options are the props from `length` to `onBlur`, and it returns `{ value, status, isFocused, cells, inputProps, focus, blur, clear, setValue }`. Spread `inputProps` on a `TextInput` laid over your cells at an opacity of `0.011`.

### Parameters
- **options** (object) - Required - Options object containing props from `length` to `onBlur`.

### Returns
- **value** (string) - The current OTP value.
- **status** (OTPStatus) - The current status of the OTP field.
- **isFocused** (boolean) - Whether the input is focused.
- **cells** (array) - Array of cell values.
- **inputProps** (object) - Props to spread on a `TextInput`.
- **focus** (function) - Focuses the input.
- **blur** (function) - Blurs the input.
- **clear** (function) - Clears the input.
- **setValue** (function) - Sets the input value.
```

--------------------------------

### Import useOTPField

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/useOTPField.md

Import the headless hook from the package. It holds field logic (value, status, cells, input props) so you can render the input and cells yourself; OTPField is built on it.

```tsx
import { useOTPField } from 'react-native-otpkit'
```

--------------------------------

### Migrate import from @sectiontn/otp-input to react-native-otpkit

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Shows the import change when migrating from @sectiontn/otp-input to react-native-otpkit. OTPTextInput and OTPTextInputHandle become OTPField and OTPFieldRef.

```diff
- import { OTPTextInput, type OTPTextInputHandle } from '@sectiontn/otp-input';
+ import { OTPField, type OTPFieldRef } from 'react-native-otpkit';
```

--------------------------------

### Run lint, typecheck, and tests

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/CONTRIBUTING.md

Run Biome lint, TypeScript typecheck, and Vitest unit tests. `yarn lint` runs Biome; `yarn format` applies fixes.

```sh
yarn lint
yarn typecheck
yarn test
```

--------------------------------

### setValue

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/OTPField.md

Fills the field as if the given text were pasted; for example, 'Your code is 123456' fills '123456'. No-op while disabled or verifying.

```APIDOC
## setValue

### Description
Fills the field as if the given text were pasted; for example, 'Your code is 123456' fills '123456'. No-op while disabled or verifying.

### Method
ref method

### Signature
`(text: string) => void`

### Parameters
- **text** (string) - Required - The text to fill into the field.

### Returns
void
```

--------------------------------

### SMS message format for WebOTP

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/guides/web.md

Message format required by WebOTP: last line is `@` + domain, then `#` + code. For `example.com`, the message is `Your code is 123456` followed by `@example.com #123456`.

```text
Your code is 123456

@example.com #123456
```

--------------------------------

### UseOTPFieldOptions

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/types.md

Options for the useOTPField hook. This interface defines the configuration options for the OTP field hook.

```APIDOC
## UseOTPFieldOptions

### Description
Options for the `useOTPField` hook.

### Properties
- **length** (number) - Optional - Default: `6` - Number of cells.
- **type** (CodeType) - Optional - Default: `'numeric'` - Accepted characters.
- **value** (string) - Optional - Controlled value.
- **defaultValue** (string) - Optional - Uncontrolled starting code.
- **onChange** ((code: string) => void) - Optional - Every change, never debounced.
- **onComplete** ((code: string) => void | Promise<unknown>) - Optional - Runs on each complete code; a promise drives verifying → success/error.
- **status** (OTPStatus) - Optional - Overrides internal status.
- **clearOnError** (boolean) - Optional - Default: `true` - Clear 600 ms after a rejected `onComplete`.
- **blurOnComplete** (boolean) - Optional - Default: `false` - Blur after a non-promise `onComplete`.
- **transform** ((text: string) => string) - Optional - Runs on all incoming text before filtering.
- **secure** (boolean) - Optional - Default: `false` - Dot in filled cells.
- **disabled** (boolean) - Optional - Default: `false` - Block focus and input.
- **onFocus** (() => void) - Optional - Focus callback.
- **onBlur** (() => void) - Optional - Blur callback.

### Accepts/produces
- The options parameter of `useOTPField`; `OTPFieldProps` inherits it minus `onFocus`/`onBlur`.
```

--------------------------------

### useOTPField(options)

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/configuration.md

Hook for managing OTP input field state. Accepts an options object to configure length, type, value, callbacks, and more.

```APIDOC
## useOTPField(options)

### Description
Hook for managing OTP input field state. Accepts an options object to configure length, type, value, callbacks, and more.

### Parameters
#### Options Object
- **length** (number) - Optional - Number of cells. Default: 6. Not a positive integer → falls back to 6.
- **type** (CodeType) - Optional - Accepted characters; also controls inputMode/autoCapitalize. Default: 'numeric'.
- **value** (string) - Optional - Controlled value.
- **defaultValue** (string) - Optional - Uncontrolled starting code.
- **onChange** ((code: string) => void) - Optional - Fires on every change.
- **onComplete** ((code: string) => void | Promise<unknown>) - Optional - Promise drives 'verifying' → 'success'/'error'.
- **status** (OTPStatus) - Optional - Overrides internal status; disables clearOnError.
- **clearOnError** (boolean) - Optional - Clear 600 ms after a rejected onComplete. Default: true.
- **blurOnComplete** (boolean) - Optional - Blur after a non-promise onComplete. Default: false.
- **transform** ((text: string) => string) - Optional - Transforms incoming text before filtering.
- **secure** (boolean) - Optional - Dot in filled cells. Default: false.
- **disabled** (boolean) - Optional - Blocks focus/input. Default: false.
- **onFocus** (() => void) - Optional - Focus callback.
- **onBlur** (() => void) - Optional - Blur callback.
```

--------------------------------

### Native appHash computation (Kotlin)

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/getAppHash.md

Computes the app hash by SHA-256 hashing the package name and signature hex, taking the first 9 bytes, Base64-encoding, and truncating to 11 characters.

```kotlin
internal fun appHash(packageName: String, signatureHex: String): String {
  val digest = MessageDigest.getInstance("SHA-256")
    .digest("$packageName $signatureHex".toByteArray(Charsets.UTF_8))
  return base64(digest.copyOf(HASH_BYTES)).take(HASH_LENGTH) // 9 bytes → 12 chars → take(11)
}
```

--------------------------------

### useSmsCode(options)

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/useSmsCode.md

React hook that listens for SMS codes using the OTPKit native module. Supports consent and retriever modes, custom extraction, and manual start control.

```APIDOC
## useSmsCode(options)

### Description
React hook that listens for SMS codes using the OTPKit native module. Supports consent and retriever modes, custom extraction, and manual start control.

### Parameters
- **options** (UseSmsCodeOptions) - Required - Configuration object with the following properties:
  - **mode** ('consent' | 'retriever') - Required - The SMS retrieval mode.
  - **length** (number) - Optional - Expected length of the SMS code.
  - **enabled** (boolean) - Optional - Whether the listener starts automatically. Defaults to true.
  - **extract** ((message: string) => string | null) - Optional - Custom function to extract the code from the SMS message.

### Returns
An object with the following properties:
- **code** (string | null) - The extracted SMS code, or null if not yet received.
- **status** (SmsStatus) - Current status: 'listening' | 'received' | 'timeout' | 'denied' | 'unavailable'.
- **start** (() => void) - Manually starts the SMS listener.

### Usage Examples

#### Listen without a field and verify when a code arrives
```tsx
import { useEffect } from 'react';
import { useSmsCode } from 'react-native-otpkit';

export function UseSms() {
  const sms = useSmsCode({ mode: 'consent', length: 6 });

  useEffect(() => {
    if (sms.code) verify(sms.code);
  }, [sms.code]);

  useEffect(() => {
    if (sms.status === 'denied') setMessage('Message sharing was denied');
  }, [sms.status]);

  return null;
}
```

#### Custom extraction and manual start
```tsx
const sms = useSmsCode({
  mode: 'consent',
  enabled: false,
  extract: (message) => message.match(/code: (\d{6})/)?.[1] ?? null,
});

// Later, with error handling around the statuses:
sms.start();
// watch sms.status: 'listening' -> 'received' (sms.code) | 'timeout' | 'denied' | 'unavailable'
```

#### With a retriever sender hash and resend
```tsx
const sms = useSmsCode({ mode: 'retriever', length: 6 });

<Button title="Resend" onPress={sms.start} />;
```
```

--------------------------------

### Add OTPKit skill for coding agents

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Command for coding agents like Claude Code, Codex and Cursor to add the OTPKit skill, which provides the API and its pitfalls.

```sh
npx skills add SectionTN/react-native-otpkit
```

--------------------------------

### Get app hash with getAppHash

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/guides/sms.md

Retrieve the app's hash on the device. The hash depends on the signing key, so debug and release builds differ; with Play App Signing, read it from a Google Play build.

```tsx
const hash = await getAppHash();
```

--------------------------------

### getAppHash

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/errors.md

Function to retrieve the app hash. Rejects with a native error if no signing certificate or native exception occurs.

```APIDOC
## getAppHash

### Description
Function to retrieve the app hash. Rejects with a native error if no signing certificate or native exception occurs.

### Failure Cases
- **No signing certificate or native exception**: Rejects with `E_NATIVE`. Catch with `getAppHash().catch(() => null)`.
```

--------------------------------

### useOTPField hook

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/guides/styling.md

Holds the field logic and leaves the drawing to you. Spread inputProps on a TextInput laid over your cells.

```APIDOC
## useOTPField hook

### Description
Holds the field logic and leaves the drawing to you. Spread inputProps on a TextInput laid over your cells.

### Usage
```tsx
import { StyleSheet, Text, TextInput, View } from 'react-native';
import { useOTPField } from 'react-native-otpkit';

export function CodeField() {
  const field = useOTPField({ length: 4, onComplete: (code) => console.log(code) });

  return (
    <View style={{ height: 80 }}>
      <View style={{ flexDirection: 'row', gap: 16, pointerEvents: 'none' }}>
        {field.cells.map((cell) => (
          <View
            key={cell.index}
            style={{ width: 56, height: 80, borderBottomWidth: 3, borderColor: cell.isActive ? '#2563EB' : '#D4D4D4' }}
          >
            <Text style={{ fontSize: 44, textAlign: 'center' }}>{cell.char}</Text>
          </View>
        ))}
      </View>
      <TextInput
        {...field.inputProps}
        accessibilityLabel="Verification code"
        style={[StyleSheet.absoluteFill, { opacity: 0.011, color: 'transparent' }]}
      />
    </View>
  );
}
```

Keep the input at an opacity of `0.011`. iOS ignores touches on views below `0.01`.
```

--------------------------------

### BigDigits custom OTP field component

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/skills/react-native-otpkit/SKILL.md

Custom OTP field component using useOTPField to render large digit cells with a hidden TextInput overlay. The component takes an onComplete callback that receives the entered code. It uses accessibilityElementsHidden and importantForAccessibility to hide the visual cells from screen readers, and the TextInput is nearly transparent (opacity 0.011) to capture input while remaining invisible.

```tsx
import { StyleSheet, Text, TextInput, View } from 'react-native';
import { useOTPField } from 'react-native-otpkit';

export function BigDigits(props: { onComplete: (code: string) => Promise<void> }) {
  const field = useOTPField({ length: 4, onComplete: props.onComplete });

  return (
    <View>
      <View
        style={styles.row}
        accessibilityElementsHidden
        importantForAccessibility="no-hide-descendants"
      >
        {field.cells.map((cell) => (
          <View
            key={cell.index}
            style={[
              styles.cell,
              cell.isActive && styles.active,
              cell.status === 'error' && styles.error,
            ]}
          >
            <Text style={styles.digit}>{cell.char}</Text>
          </View>
        ))}
      </View>
      <TextInput
        {...field.inputProps}
        accessibilityLabel="Verification code"
        style={[StyleSheet.absoluteFill, styles.input]}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  row: { flexDirection: 'row', gap: 16, pointerEvents: 'none' },
  cell: {
    width: 56,
    height: 72,
    borderBottomWidth: 3,
    borderColor: '#D4D4D4',
    alignItems: 'center',
    justifyContent: 'center',
  },
  active: { borderColor: '#2563EB' },
  error: { borderColor: '#DC2626' },
  digit: { fontSize: 40, fontWeight: '700' },
  input: { opacity: 0.011, color: 'transparent' },
});
```

--------------------------------

### OTPField placeholder and secure

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/guides/styling.md

placeholder shows one character in each empty cell, and secure draws a dot in each filled one.

```APIDOC
## OTPField placeholder and secure

### Description
placeholder shows one character in each empty cell, and secure draws a dot in each filled one.

### Usage
```tsx
<OTPField placeholder="•" />
<OTPField secure />
```
```

--------------------------------

### Placeholder and secure dots

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/guides/styling.md

`placeholder` shows one character in each empty cell, and `secure` draws a dot in each filled one.

```tsx
<OTPField placeholder="•" />
<OTPField secure />
```

--------------------------------

### focus

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/OTPField.md

Shows the keyboard for the OTP field. No-op while the field is disabled.

```APIDOC
## focus

### Description
Shows the keyboard for the OTP field. No-op while the field is disabled.

### Method
ref method

### Signature
`() => void`

### Parameters
None

### Returns
void
```

--------------------------------

### useOTPField with async verification and reset

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/useOTPField.md

Configures onComplete to call verify, which rejects on wrong code. Uses clearOnError: false, type 'alphanumeric', and a transform that removes whitespace.

```tsx
const field = useOTPField({
  onComplete: (code) => verify(code), // rejects on a wrong code
  clearOnError: false,
  type: 'alphanumeric',
  transform: (text) => text.replace(/\s/g, ''),
});
```

--------------------------------

### UseOTPFieldOptions interface

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/useOTPField.md

Options for configuring the OTP field. Defaults: length 6, type 'numeric', clearOnError true, blurOnComplete false, secure false, disabled false. onChange is never debounced; value is always sanitized; status overrides internal status.

```tsx
interface UseOTPFieldOptions {
  length?: number;            // Default 6.
  type?: CodeType;            // Default 'numeric'.
  value?: string;             // Controlled value.
  defaultValue?: string;      // Starting code, uncontrolled.
  onChange?: (code: string) => void;          // Never debounced.
  onComplete?: (code: string) => void | Promise<unknown>;
  status?: OTPStatus;                         // Overrides internal status.
  clearOnError?: boolean;                     // Default true.
  blurOnComplete?: boolean;                   // Default false.
  transform?: (text: string) => string;
  secure?: boolean;                           // Default false.
  disabled?: boolean;                         // Default false.
  onFocus?: () => void;
  onBlur?: () => void;
}
```

--------------------------------

### OTPField.onComplete

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/errors.md

Callback for OTP completion. Handles promise rejections and stale results, with configurable error behavior.

```APIDOC
## OTPField.onComplete

### Description
Callback for OTP completion. Handles promise rejections and stale results, with configurable error behavior.

### Failure Cases
- **Promise rejects** (e.g. wrong code): `field.status` becomes `'error'`; cells shake; after 600 ms the code clears and the field refocuses (unless `clearOnError={false}` or a `status` prop overrides). Catch in the `onComplete` implementation and/or drive UI from a `status` prop.
- **New code lands while previous check is pending**: Later promise result is dropped (attempt counter). Not an error — stale results are ignored.
```

--------------------------------

### Web implementation of getAppHash (TypeScript)

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/api-reference/getAppHash.md

Web implementation that always resolves to null, as there is no native module on web.

```tsx
// Web implementation, src/sms/getAppHash.web.ts
export function getAppHash(): Promise<string | null> {
  return Promise.resolve(null);
}
```

--------------------------------

### OTPField Methods

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Imperative methods available on the OTPField component instance for controlling focus, clearing, setting values, and SMS listening.

```APIDOC
## OTPField Methods

### Description
Imperative methods available on the OTPField component instance for controlling focus, clearing, setting values, and SMS listening.

### Methods

| Method | Description |
| --- | --- |
| `focus()`, `blur()` | Show or hide the keyboard. |
| `clear()` | Empty the field. A pending `onComplete` promise is then ignored. |
| `setValue(text)` | Fill the field as if `text` were pasted. `'Your code is 123456'` fills `123456`. |
| `listenForSms()` | Listen for the SMS again, for example after a resend. It does nothing unless `sms` is set. |
```

--------------------------------

### getAppHash promise rejection catch

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/errors.md

Catch a real promise rejection from getAppHash and return null as a fallback.

```tsx
// getAppHash — a real promise rejection to catch
const hash = await getAppHash().catch(() => null);
```

--------------------------------

### getAppHash()

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/README.md

Resolves to the 11-character hash a Retriever message must contain, or to null off Android. The hash comes from the signing key, so debug and release builds have different ones.

```APIDOC
## getAppHash()

### Description
Resolves to the 11-character hash a Retriever message must contain, or to `null` off Android. The hash comes from the signing key, so debug and release builds have different ones.

### Returns
- **Promise<string|null>** - The app hash string on Android, or null on other platforms.
```

--------------------------------

### useSmsCode(options)

Source: https://github.com/sectiontn/react-native-otpkit/blob/main/_autodocs/configuration.md

Hook for SMS code extraction. Accepts an options object to configure mode, sender, length, type, extraction, and enabled state.

```APIDOC
## useSmsCode(options)

### Description
Hook for SMS code extraction. Accepts an options object to configure mode, sender, length, type, extraction, and enabled state.

### Parameters
#### Options Object
- **mode** (SmsMode) - Required - 'consent' or 'retriever' (web: both use WebOTP).
- **sender** (string) - Optional - Consent only; restrict to one phone number.
- **length** (number) - Optional - Default extraction length. Default: 6.
- **type** (CodeType) - Optional - Default extraction characters. Default: 'numeric'.
- **extract** ((message: string) => string | null) - Optional - Custom extraction (ignored on web).
- **enabled** (boolean) - Optional - false waits for start(). Default: true.
```
Tokens:
Raw