Building a Lightweight Biometric Authentication Library for React Native with Kotlin

Hello developers!

Today, I want to share a quick story about a common challenge I faced while working with React Native: securing app access with biometric authentication, and why I decided to build and open-source my own library:

@vijeshkr/react-native-biometric-auth

The Spark: Why Another Biometric Library?

While working on a mobile application that required secure user authentication, such as unlocking the app when it launches, I came across a few challenges with existing solutions.

1. Clunky Fallback Support

Handling fallback authentication can sometimes require additional configuration.

I wanted a solution where users could authenticate using biometrics while also having the option to fall back to their device credentials, such as:

• Fingerprint
• Device PIN
• Pattern
• Password

2. Legacy Native Dependencies

I also wanted to avoid relying on older Java-based implementations and instead use modern Android APIs with Kotlin and AndroidX Biometric.

3. Keeping Things Lightweight

For this particular use case, I wanted something simple:

• A lightweight native module
• A clean JavaScript/TypeScript API
• Modern Android biometric APIs
• Promise-based authentication
• Minimal configuration

So, instead of working around those limitations, I decided to build my own native module.

Introducing @vijeshkr/react-native-biometric-auth

@vijeshkr/react-native-biometric-auth is an Android biometric authentication library for React Native, built with Kotlin and AndroidX Biometric.

It provides biometric authentication with optional device credential fallback.

Key Features

• Kotlin Native Module — Built entirely with Kotlin.
• AndroidX Biometric — Uses Android's modern BiometricPrompt APIs.
• Device Credential Fallback — Supports PIN, Pattern, or Password fallback.
• Promise-Based API — Works naturally with async/await.
• TypeScript Support — Includes TypeScript definitions for a better developer experience.
• Simple React Native Integration — Minimal setup and a straightforward API.

Getting Started

1. Installation

Install the package using npm:

npm install @vijeshkr/react-native-biometric-auth

Or using Yarn:

yarn add @vijeshkr/react-native-biometric-auth

2. Check Availability and Authenticate

Once installed, you can check whether authentication is available and then trigger the native Android authentication prompt.

import React from 'react';
import { Button, Alert, SafeAreaView } from 'react-native';
import { BiometricAuth } from '@vijeshkr/react-native-biometric-auth';

export default function App() {
  const handleAuthentication = async () => {
    try {
      // 1. Check if biometrics or device credentials are available
      const isAvailable = await BiometricAuth.isBiometricAvailable();

      if (!isAvailable) {
        Alert.alert(
          'Unavailable',
          'Biometrics or device credentials are not set up on this device.'
        );
        return;
      }

      // 2. Trigger native BiometricPrompt
      const success = await BiometricAuth.authenticate({
        title: 'Unlock Application',
        subtitle: 'Touch fingerprint sensor or enter device PIN',
        cancelText: 'Cancel',
        allowDeviceCredential: true,
      });

      if (success) {
        Alert.alert('Success', 'Welcome back!');
      }
    } catch (error) {
      console.error('Authentication Error:', error);

      Alert.alert(
        'Error',
        'Authentication failed or was cancelled.'
      );
    }
  };

  return (
    <SafeAreaView
      style={{
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
      }}
    >
      <Button
        title="Unlock App with Biometrics"
        onPress={handleAuthentication}
      />
    </SafeAreaView>
  );
}

The API is intentionally simple: check availability, call authenticate(), and handle the returned promise.

How Does It Work Under the Hood?

The native Android implementation is written entirely in Kotlin.

The module uses Android's:

• BiometricPrompt
• BiometricManager
• androidx.biometric

When allowDeviceCredential: true is enabled, the authentication flow allows the device credential to be used as a fallback.

Conceptually, the authentication configuration uses:

BIOMETRIC_STRONG or DEVICE_CREDENTIAL

This allows the user to authenticate using a supported strong biometric or their configured device credential, depending on the device and authentication setup.

For example, if biometric authentication isn't available or the user chooses the available fallback, the device can use credentials such as a PIN, Pattern, or Password.

This is one of the main reasons I wanted to build the module around the modern Android biometric APIs rather than implementing the authentication flow manually.

Why Kotlin?

One of my goals with this project was to get more comfortable with the native side of React Native.

React Native doesn't mean you only work with JavaScript or TypeScript.

Sometimes you need to go one layer deeper and interact directly with:

React Native → Native Module → Android APIs

For this project, Kotlin was a good fit because the Android side could remain small and focused while still taking advantage of modern Android APIs.

Building this module also helped me better understand how React Native communicates with native Android code through a custom native module.

Open Source

The project is open source, and I'd love for other React Native developers to try it out and share their feedback.

NPM Package: @vijeshkr/react-native-biometric-auth

GitHub Repository: vijeshkr/react-native-biometric-auth

If you find the project useful, consider giving it a star on GitHub.

What's Next?

This is currently focused on Android biometric authentication.

There are several things I would like to explore as the project evolves, including improvements to the authentication flow, documentation, testing, and potentially broader platform support.

I also want to continue improving my understanding of React Native's native module architecture through projects like this.

Let's Discuss

I'd love to hear from other React Native developers.

Have you faced any challenges while implementing biometric or native authentication in React Native?

Or:

What feature would you like to see added to this library next?

Feel free to share your experience or suggestions in the comments.

Happy coding!