Capacitor Native Biometric

Use biometrics confirm device owner presence or authenticate users. A couple of methods are provided to handle user credentials. These are securely stored using Keychain (iOS) and Keystore (Android).

Why Native Biometric?

A free, comprehensive biometric authentication plugin with secure credential storage:

• All biometric types - Face ID, Touch ID, Fingerprint, Face Authentication, Iris
• Secure credential storage - Keychain (iOS) and Keystore (Android) integration
• Flexible fallback - Optional passcode fallback when biometrics unavailable
• Customizable UI - Full control over prompts, titles, descriptions, button text
• Detailed error codes - Unified error handling across iOS and Android
• Resume listener - Detect biometry availability changes when app returns from background
• Modern package management - Supports both Swift Package Manager (SPM) and CocoaPods (SPM-ready for Capacitor 8)

Perfect for banking apps, password managers, authentication flows, and any app requiring secure user verification.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/native-biometric/

Installation (Only supports Capacitor 7)

• npm i @capgo/capacitor-native-biometric

Usage

import { NativeBiometric, BiometryType } from "@capgo/capacitor-native-biometric";

async performBiometricVerification(){
  const result = await NativeBiometric.isAvailable();

  if(!result.isAvailable) return;

  // Check the biometry type for display purposes
  // IMPORTANT: Always use isAvailable for logic decisions, not biometryType
  const isFaceID = result.biometryType == BiometryType.FACE_ID;

  // Check if device has PIN/pattern/password set
  console.log('Device is secure:', result.deviceIsSecure);

  // Check if strong biometry (Face ID, Touch ID, fingerprint) is available
  console.log('Strong biometry available:', result.strongBiometryIsAvailable);

  const verified = await NativeBiometric.verifyIdentity({
    reason: "For easy log in",
    title: "Log in",
    subtitle: "Maybe add subtitle here?",
    description: "Maybe a description too?",
  })
    .then(() => true)
    .catch(() => false);

  if(!verified) return;

  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });
}

// Save user's credentials
NativeBiometric.setCredentials({
  username: "username",
  password: "password",
  server: "www.example.com",
}).then();

// Delete user's credentials
NativeBiometric.deleteCredentials({
  server: "www.example.com",
}).then();

// Listen for biometry availability changes when app resumes from background
const handle = await NativeBiometric.addListener('biometryChange', (result) => {
  console.log('Biometry availability changed:', result.isAvailable);
  console.log('Biometry type:', result.biometryType);
});

// To remove the listener when no longer needed:
// await handle.remove();

Biometric Auth Errors

This is a plugin specific list of error codes that can be thrown on verifyIdentity failure, or set as a part of isAvailable. It consolidates Android and iOS specific Authentication Error codes into one combined error list.

| 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 |

• isAvailable(...)
• addListener('biometryChange', ...)
• verifyIdentity(...)
• getCredentials(...)
• setCredentials(...)
• deleteCredentials(...)
• isCredentialsSaved(...)
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

isAvailable(...)

isAvailable(options?: IsAvailableOptions | undefined) => Promise<AvailableResult>

Checks if biometric authentication hardware is available.

| Param | Type | | ------------- | ----------------------------------------------------------------- | | options | IsAvailableOptions |

Returns: Promise<AvailableResult>

Since: 1.0.0

addListener('biometryChange', ...)

addListener(eventName: 'biometryChange', listener: BiometryChangeListener) => Promise<PluginListenerHandle>

Adds a listener that is called when the app resumes from background. This is useful to detect if biometry availability has changed while the app was in the background (e.g., user enrolled/unenrolled biometrics).

| Param | Type | Description | | --------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | eventName | 'biometryChange' | - Must be 'biometryChange' | | listener | BiometryChangeListener | - Callback function that receives the updated AvailableResult |

Returns: Promise<PluginListenerHandle>

Since: 7.6.0

verifyIdentity(...)

verifyIdentity(options?: BiometricOptions | undefined) => Promise<void>

Prompts the user to authenticate with biometrics.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | BiometricOptions |

Since: 1.0.0

getCredentials(...)

getCredentials(options: GetCredentialOptions) => Promise<Credentials>

Gets the stored credentials for a given server.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | GetCredentialOptions |

Returns: Promise<Credentials>

Since: 1.0.0

setCredentials(...)

setCredentials(options: SetCredentialOptions) => Promise<void>

Stores the given credentials for a given server.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | SetCredentialOptions |

Since: 1.0.0

deleteCredentials(...)

deleteCredentials(options: DeleteCredentialOptions) => Promise<void>

Deletes the stored credentials for a given server.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | DeleteCredentialOptions |

Since: 1.0.0

isCredentialsSaved(...)

isCredentialsSaved(options: IsCredentialsSavedOptions) => Promise<IsCredentialsSavedResult>

Checks if credentials are already saved for a given server.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | IsCredentialsSavedOptions |

Returns: Promise<IsCredentialsSavedResult>

Since: 7.3.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

AvailableResult

Result from isAvailable() method indicating biometric authentication availability.

| Prop | Type | Description | | ------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isAvailable | boolean | Whether authentication is available (biometric or fallback if useFallback is true) | | authenticationStrength | AuthenticationStrength | The strength of available authentication method (STRONG, WEAK, or NONE) | | biometryType | BiometryType | The primary biometry type available on the device. On Android devices with multiple biometry types, this returns MULTIPLE. Use this for display purposes only - always use isAvailable for logic decisions. | | deviceIsSecure | boolean | Whether the device has a secure lock screen (PIN, pattern, or password). This is independent of biometric enrollment. | | strongBiometryIsAvailable | boolean | Whether strong biometry (Face ID, Touch ID, or fingerprint on devices that consider it strong) is specifically available, separate from weak biometry or device credentials. | | errorCode | BiometricAuthError | Error code from BiometricAuthError enum. Only present when isAvailable is false. Indicates why biometric authentication is not available. |

IsAvailableOptions

| Prop | Type | Description | | ----------------- | -------------------- | ----------------------------------------------------------------------------------------------------- | | useFallback | boolean | Specifies if should fallback to passcode authentication if biometric authentication is not available. |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

BiometricOptions

| Prop | Type | Description | Default | | -------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | reason | string | | | | title | string | | | | subtitle | string | | | | description | string | | | | negativeButtonText | string | | | | useFallback | boolean | Specifies if should fallback to passcode authentication if biometric authentication fails. | | | fallbackTitle | string | Only for iOS. Set the text for the fallback button in the authentication dialog. If this property is not specified, the default text is set by the system. | | | maxAttempts | number | Only for Android. Set a maximum number of attempts for biometric authentication. The maximum allowed by android is 5. | 1 | | allowedBiometryTypes | BiometryType[] | Only for Android. Specify which biometry types are allowed for authentication. If not specified, all available types will be allowed. | |

Credentials

| Prop | Type | | -------------- | ------------------- | | username | string | | password | string |

GetCredentialOptions

| Prop | Type | | ------------ | ------------------- | | server | string |

SetCredentialOptions

| Prop | Type | | -------------- | ------------------- | | username | string | | password | string | | server | string |

DeleteCredentialOptions

| Prop | Type | | ------------ | ------------------- | | server | string |

IsCredentialsSavedResult

| Prop | Type | | ------------- | -------------------- | | isSaved | boolean |

IsCredentialsSavedOptions

| Prop | Type | | ------------ | ------------------- | | server | string |

Type Aliases

BiometryChangeListener

Callback type for biometry change listener

(result: AvailableResult): void

Enums

AuthenticationStrength

| Members | Value | Description | | ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | NONE | 0 | No authentication available, even if PIN is available but useFallback = false | | STRONG | 1 | Strong authentication: Face ID on iOS, fingerprints on devices that consider fingerprints strong (Android). Note: PIN/pattern/password is NEVER considered STRONG, even when useFallback = true. | | WEAK | 2 | Weak authentication: Face authentication on Android devices that consider face weak, or PIN/pattern/password if useFallback = true (PIN is always WEAK, never STRONG). |

BiometryType

| Members | Value | | ------------------------- | -------------- | | NONE | 0 | | TOUCH_ID | 1 | | FACE_ID | 2 | | FINGERPRINT | 3 | | FACE_AUTHENTICATION | 4 | | IRIS_AUTHENTICATION | 5 | | MULTIPLE | 6 |

BiometricAuthError

| Members | Value | Description | | ----------------------------- | --------------- | ------------------------------------------------------------------------------------- | | UNKNOWN_ERROR | 0 | Unknown error occurred | | BIOMETRICS_UNAVAILABLE | 1 | Biometrics are unavailable (no hardware or hardware error) Platform: Android, iOS | | USER_LOCKOUT | 2 | User has been locked out due to too many failed attempts Platform: Android, iOS | | BIOMETRICS_NOT_ENROLLED | 3 | No biometrics are enrolled on the device Platform: Android, iOS | | USER_TEMPORARY_LOCKOUT | 4 | User is temporarily locked out (Android: 30 second lockout) Platform: Android | | AUTHENTICATION_FAILED | 10 | Authentication failed (user did not authenticate successfully) Platform: Android, iOS | | APP_CANCEL | 11 | App canceled the authentication (iOS only) Platform: iOS | | INVALID_CONTEXT | 12 | Invalid context (iOS only) Platform: iOS | | NOT_INTERACTIVE | 13 | Authentication was not interactive (iOS only) Platform: iOS | | PASSCODE_NOT_SET | 14 | Passcode/PIN is not set on the device Platform: Android, iOS | | SYSTEM_CANCEL | 15 | System canceled the authentication (e.g., due to screen lock) Platform: Android, iOS | | USER_CANCEL | 16 | User canceled the authentication Platform: Android, iOS | | USER_FALLBACK | 17 | User chose to use fallback authentication method Platform: Android, iOS |

To use FaceID Make sure to provide a value for NSFaceIDUsageDescription, otherwise your app may crash on iOS devices with FaceID.

This value is just the reason for using FaceID. You can add something like the following example to App/info.plist:

<key>NSFaceIDUsageDescription</key>
<string>For an easier and faster log in.</string>

Biometric (Android)

To use android's BiometricPrompt api you must add the following permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.USE_BIOMETRIC">

Important Note About biometryType on Android

The biometryType field indicates what biometric hardware is present, but hardware presence does not guarantee availability. Some Android devices report face authentication hardware but don't make it available to apps.

Always use isAvailable for logic decisions, not biometryType. The biometryType field should only be used for display purposes (e.g., showing "Use Face ID" vs "Use Fingerprint" in your UI).

Web Platform

This plugin does not support web browsers. On web:

• isAvailable() returns { isAvailable: false, ... } (no error thrown)
• addListener() returns a no-op handle
• verifyIdentity() throws an error
• Credential methods throw errors

This allows you to safely check availability on web without try/catch, but authentication features are only available on iOS and Android.

Contributors

Jonthia QliQ.dev Brian Weasner Mohamed Diarra

Want to Contribute?

Learn about contributing HERE

Notes

Hasn't been tested on Android API level 22 or lower.