---
title: Announcing the Capacitor Biometrics Plugin
description: The new Capacitor Biometrics plugin allows you to request biometric authentication, such as using face recognition or fingerprint recognition, on the device.
date: 
  created: 2025-05-01
  updated: 2026-07-10
authors:
  - robingenz
categories:
  - Announcements
  - Capacitor
  - SDKs
links:
  - Capacitor Biometrics: sdks/capacitor/biometrics.md
faq: true
---

# Capacitor Biometrics Plugin: Face & Fingerprint

Adding Face ID or fingerprint login to a Capacitor app? The [Capacitor Biometrics plugin](../../sdks/capacitor/biometrics.md) lets you request **biometric authentication** (Face ID, fingerprint) and device credentials (PIN, pattern, password) on Android and iOS through a single API. It's available to all Capawesome [Insiders](../../insiders/index.md).

<!-- more -->

Let's take a quick look at the [API](../../sdks/capacitor/biometrics.md#api) and how to use the plugin in your Capacitor app.

## Bonus: Video Tutorial and Demo App

We created a **step-by-step video tutorial** that walks through installing the plugin, configuring iOS Face ID permissions, organizing your biometrics logic in a small helper module, triggering authentication from the app UI, and handling success and error states.

<div style="margin-top: 2rem;">
  <iframe
    width="100%"
    height="450px"
    src="https://www.youtube-nocookie.com/embed/ixUvTX6n7x8?si=USWRrbmg7nKgBg4A?rel=0&modestbranding=1"
    frameborder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    referrerpolicy="strict-origin-when-cross-origin"
    allowfullscreen
  ></iframe>
</div>

- **[Capacitor Biometrics Demo App](https://github.com/capawesome-team/capacitor-biometrics-demo){:target="_blank"}** — A minimal, framework-agnostic demo (vanilla JavaScript and Capacitor) with a complete biometric authentication flow using Face ID or fingerprint.

## Installation

To install the Capacitor Biometrics plugin, please refer to the [Installation](../../sdks/capacitor/biometrics.md/#installation) section in the plugin documentation.

## Usage

Let's take a look at the basic usage of the plugin. You can find the complete API reference in the [API](../../sdks/capacitor/biometrics.md#api) section of the documentation. The plugin supports both **biometric authentication** and **device credential authentication**.
Biometric authentication uses the device's biometric capabilities, such as fingerprint or face recognition, while device credential authentication uses the device's lock screen PIN, pattern, or password.

### Biometric Authentication

The most important method of the plugin is [`authenticate()`](../../sdks/capacitor/biometrics.md#authenticate), which allows you to request biometric authentication from the user.
You can customize the authentication prompt with various options, such as the title, subtitle, and button text:

```typescript
import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics';


const authenticate = async () => {
  try {
    await Biometrics.authenticate({
      title: 'Authentication Required',
      subtitle: 'Please authenticate to continue',
      cancelButtonText: 'Cancel',
      iosFallbackButtonText: 'Use Passcode',
    });
  } catch (error) {
    if (error.code === ErrorCode.USER_CANCELED) {
      console.log('User canceled the authentication.');
    } else if (error.code === ErrorCode.NOT_ENROLLED) {
      console.log('No biometric authentication enrolled.');
    } else if (error.code === ErrorCode.NOT_AVAILABLE) {
      console.log('Biometric authentication not available.');
    } else {
      console.log('Another error occurred:', error);
    }
  }
};
```

The method returns a promise that resolves when the user successfully authenticates or rejects with an error if the user cancels the authentication or if there is an error during the authentication process.
You can handle the error using the `catch` block, where you can check the error code to determine the reason for the failure.
The error codes are defined in the `ErrorCode` enum.

In most cases, you will also want to use the [`isEnrolled()`](../../sdks/capacitor/biometrics.md#isenrolled) method to check whether the device supports biometric authentication at all and whether the user has set it up:

```typescript
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const isEnrolled = async () => {
  const result = await Biometrics.isEnrolled();
  if (result.isEnrolled) {
    console.log('Biometric authentication is enrolled.');
  } else {
    console.log('No biometric authentication enrolled.');
  }
};
```

It's recommended to call this method before calling [`authenticate()`](../../sdks/capacitor/biometrics.md#authenticate) to ensure that the user has set up biometric authentication on their device.

### Device Credential Authentication

In addition to biometric authentication, the plugin also supports device credential authentication using the [`authenticate()`](../../sdks/capacitor/biometrics.md#authenticate) method.
For this, you need to set the `allowDeviceCredential` option to `true` when calling the method:

```typescript
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const authenticate = async () => {
    await Biometrics.authenticate({
      allowDeviceCredential: true,
    });
};
```

This will show the device's lock screen PIN, pattern, or password prompt if biometric authentication is not available or not enrolled.
You can also use the [`hasDeviceCredential()`](../../sdks/capacitor/biometrics.md#hasdevicecredential) method to check whether the device supports device credential authentication:

```typescript
import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const hasDeviceCredential = async () => {
  const { hasDeviceCredential } = await Biometrics.hasDeviceCredential();
  return hasDeviceCredential;
};
```

## FAQ

### Which platforms does the Capacitor Biometrics plugin support?

The plugin supports Android and iOS through a single API for both biometric and device-credential authentication.

### How do I check whether biometrics are set up before prompting?

Call `isEnrolled()` first. It tells you whether the device supports biometric authentication and whether the user has enrolled it, so you can decide whether to show the prompt or fall back to another method.

### Can users authenticate with a PIN or passcode instead of biometrics?

Yes. Pass `allowDeviceCredential: true` to `authenticate()` to allow the device's lock-screen PIN, pattern, or password, and use `hasDeviceCredential()` to check whether the device supports it.

### How do I handle the user canceling the prompt?

`authenticate()` rejects with a typed `ErrorCode` — such as `USER_CANCELED`, `NOT_ENROLLED`, or `NOT_AVAILABLE` — so you can branch on the exact reason in your `catch` block.

## Conclusion

The [Capacitor Biometrics plugin](../../sdks/capacitor/biometrics.md) gives you Face ID, fingerprint, and device-credential authentication behind one API on Android and iOS. Check the [API Reference](../../sdks/capacitor/biometrics.md#api) for the full surface area.

**Related reading:**

- [Exploring the Capacitor Biometrics API](./exploring-the-capacitor-biometrics-api.md)
- [How to Securely Store Credentials with Capacitor](./how-to-securely-store-credentials-with-capacitor.md)
- [Alternative to the Ionic Identity Vault plugin](./alternative-to-ionic-identity-vault-plugin.md)
- [Capacitor Privacy Screen: Hide Sensitive App Content](./capacitor-privacy-screen-hide-app-content.md)

**Missing a feature?** [Create a feature request](https://github.com/capawesome-team/capacitor-plugins/issues/new/choose){:target="_blank"} in our [GitHub repository](https://github.com/capawesome-team/capacitor-plugins){:target="_blank"}.

Join the Capawesome [Discord](https://discord.gg/VCXxSVjefW){:target="_blank"} server for questions and subscribe to the Capawesome [newsletter](https://capawesome.io/newsletter/){:target="_blank"} to stay updated.