@exodus/react-native-biometrics

A biometric authentication library for Android platform using the BiometricPrompt API.

Installation

npm install @exodus/react-native-biometrics

Usage

import Biometrics from '@exodus/react-native-biometrics';

// ...

const valid = await Biometrics.authenticate(
  'Authenticate to continue',
  'Use your fingerprint to authenticate',
  'Cancel',
);

Props

| Name | Type | Description | | ---- | ---- | ----------- | | title | string | The title of the biometric prompt | | subtitle | string | The subtitle of the biometric prompt | | cancelButtonText | string | The text of the cancel button | | fallbackToPasscode | boolean | Allow the device PIN, pattern, or password as an alternative to biometrics (default: false) |

With passcode fallback enabled, Android 10 (API 29) uses the system credential activity so switching from fingerprint to PIN does not cancel authentication. The system controls the available authentication methods, and the promise resolves from the activity result. This activity can background the app; callers must keep the pending authentication alive across that transition.

Android 9 (API 28) accepts Class 2 (weak) or Class 3 (strong) biometrics alongside device credentials because AndroidX does not support BIOMETRIC_STRONG | DEVICE_CREDENTIAL on that version. Other Android versions, and biometric-only authentication on all versions, continue to require Class 3 biometrics. Authentication does not use a CryptoObject.

Android tests

With JDK 17, Gradle 8.12, Android SDK 36, and build tools 36.0.0 installed:

gradle -p test/android :biometrics:testDebugUnitTest

The tests use the library's AndroidX dependency and Robolectric to validate prompt creation on API 27, 28, 29, and 30, including the previously rejected combination. They also cover Android 10 credential activity results, cancellation, and stale results from a replaced authentication request.

License

MIT

Made with create-react-native-library