Using @capgo/capacitor-native-biometric Package

The @capgo/capacitor-native-biometric package allows you to use biometric authentication in your Capacitor applications. This package provides methods for checking the availability of biometric authentication hardware, verifying the user's identity, and handling user credentials securely. Here is a step-by-step tutorial on how to use this package:


To install the @capgo/capacitor-native-biometric package, run the following command:

npm i @capgo/capacitor-native-biometric

Make sure you have Capacitor version 5 installed in your project.


  1. Import the NativeBiometric class from the @capgo/capacitor-native-biometric package:
import { NativeBiometric } from "@capgo/capacitor-native-biometric";
  1. Check if biometric authentication hardware is available by calling the isAvailable method:
const result = await NativeBiometric.isAvailable();

if (!result.isAvailable) {
  // Biometric authentication is not available
  1. Verify the user's identity by calling the verifyIdentity method:
const verified = await NativeBiometric.verifyIdentity({
  reason: "For easy login",
  title: "Login",
  subtitle: "Maybe add subtitle here?",
  description: "Maybe a description too?",
  .then(() => true)
  .catch(() => false);

if (!verified) {
  // User identity verification failed
  1. Retrieve the user's credentials by calling the getCredentials method:
const credentials = await NativeBiometric.getCredentials({
  server: "",
  1. Save the user's credentials by calling the setCredentials method:
  username: "username",
  password: "password",
  server: "",
}).then(() => {
  // Credentials saved successfully
  1. Delete the user's credentials by calling the deleteCredentials method:
  server: "",
}).then(() => {
  // Credentials deleted successfully

Error Handling

The @capgo/capacitor-native-biometric package provides a list of error codes that can be thrown during the biometric authentication process. These error codes are consolidated across Android and iOS platforms. Here is the list of error codes:

Code Description Platform
0 Unknown Error Android, iOS
1 Biometrics Unavailable Android, iOS
2 User Lockout Android, iOS
3 Biometrics Not Enrolled Android, iOS
4 User Temporary Lockout Android (Lockout for 30sec)
10 Authentication Failed Android, iOS
11 App Cancel iOS
12 Invalid Context iOS
13 Not Interactive iOS
14 Passcode Not Set Android, iOS
15 System Cancel Android, iOS
16 User Cancel Android, iOS
17 User Fallback Android, iOS

You can handle these error codes based on your application's requirements.

That's it! You have successfully learned how to use the @capgo/capacitor-native-biometric package to incorporate biometric authentication into your Capacitor applications.