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