react-native-biometry-tools

A lightweight library for determining the supported type of biometrics.

📋 Requirements

| Requirement | Version | | --------------------- | -------- | | React Native | ≥ 0.75 | | react-native-nitro-modules | ≥ 0.35 | | iOS | ≥ 15.1 | | Android minSdkVersion | ≥ 24 |

Note: This library uses Nitro Modules.

📥 Installation

yarn add @kode-frontend/react-native-biometry-tools react-native-nitro-modules

iOS

cd example/ios && pod install

🎮 Usage

import BiometryTools, { BiometryType, isAuthenticationCanceledError } from '@kode-frontend/react-native-biometry-tools';

export default function App() {

  React.useEffect(() => {
    // Async: check if biometry is available and enrolled
    BiometryTools
      .isSensorAvailable()
      .then((biometryType) => {
          // sensor available
          // biometryType - supported biometry
      })
      .catch((e) => {
        // sensor not available
        // biometry not supported or not enrolled
        console.log(e.message)
        console.log(e.code)
      })

    // Async: get supported biometry type even if not enrolled
    BiometryTools
      .getSupportedBiometryType()
      .then((biometryType) => {
          // even if biometry not enrolled
          // biometryType - supported biometry, if biometry not supported then return null
      })

    // Sync: instantly check if biometry is available and enrolled
    const biometryType = BiometryTools.isSensorAvailableSync();
    if (biometryType) {
      console.log('Available biometry:', biometryType);
    }

    // Sync: instantly get supported biometry type even if not enrolled
    const supportedType = BiometryTools.getSupportedBiometryTypeSync();
    console.log('Supported biometry:', supportedType); // null if not supported
  }, []);

  return (
    <Button
        title="Prompt authentication"
        onPress={() => {
          BiometryTools.authenticate('Title', { 
            subtitle: 'subtitle',
            description: 'description', 
            withDeviceCredentials: true, 
            cancelText: 'Cancel' 
          })
            .then((result) => {
              console.log('Prompt result:', result);
            })
            .catch((e) => {
              if (isAuthenticationCanceledError(e)) {
                return console.log('Cancelled by user')
              }
              console.log('Prompt error:', e.message);
            });
        }}
      />
  );
}

📦 Available methods

| Method | Returns | Description | | --------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- | | isSensorAvailable() | Promise<BiometryType> | Returns supported biometry type if biometry is available and enrolled, otherwise throws BiometryError | | isSensorAvailableSync() | BiometryType \| null | Synchronous version of isSensorAvailable. Returns null instead of throwing | | getSupportedBiometryType() | Promise<BiometryType \| null> | Returns supported biometry type if hardware is present, null otherwise. Does not require enrollment | | getSupportedBiometryTypeSync() | BiometryType \| null | Synchronous version of getSupportedBiometryType | | authenticate(title: string, options: AuthenticateOptions) | Promise<AuthenticationResult> | Shows the biometry prompt and resolves with the authentication result |

Sync methods

isSensorAvailableSync() and getSupportedBiometryTypeSync() execute on the JS thread without bridging overhead. Use them when you need the biometry status immediately on render — for example, to conditionally show a biometry button before any async operation completes.

// Render a biometry icon without waiting for a promise
const biometryType = BiometryTools.getSupportedBiometryTypeSync();

Types

enum BiometryType {
  // ios only
  FACE_ID = 'Face ID',
  TOUCH_ID = 'Touch ID',
  // android only
  FINGERPRINT = 'Fingerprint',
  FACE = 'Face',
  IRIS = 'Iris'
}


enum BiometryErrorCode {
  // common  
  NOT_SUPPORTED = 'BiometryScannerNotSupported',
  NOT_ENROLLED = 'BiometryScannerNotEnrolled',
  // ios only
  NOT_AVAILABLE = 'BiometryScannerNotAvailable',
  PASSCODE_NOT_SET = 'PasscodeNotSet',
  DEVICE_LOCKED_PERMANENT = 'DeviceLockedPermanent'

  // authentication
  AUTHENTICATION_CANCELED = 'AuthenticationCanceledByUser',
}

type AuthenticateOptions = {
  withDeviceCredentials?: boolean,
  /**
   * Cancel button text. Android only
   */
  cancelText?: string,
  /**
   * Subtitle for prompt. Android only
   */
  subtitle?: string,
  /**
   * Description for prompt. Android only
   */
  description?: string,
}

Builds

release - create release tag and increase version