Framework-agnostic biometric authentication library. Works with React, Vue, Angular, or vanilla JS. No providers required!
npm install capacitor-biometric-authenticationA framework-agnostic biometric authentication library for React, Vue, Angular, or vanilla JavaScript. No providers required!
- AI Integration Guide - Complete full-stack integration with backend package
- Backend Package - Server-side WebAuthn implementation
- Zero Dependencies - Works without any specific framework (Capacitor optional)
- Provider-less - Direct API like Zustand, no Context/Providers needed
- Multi-Platform - Web (WebAuthn), iOS, Android, Electron support
- Framework Agnostic - Works with React, Vue, Angular, Vanilla JS
- TypeScript First - Full type safety and IntelliSense
- Secure by Default - Platform-specific secure storage
- Tiny Bundle - Tree-shakeable with dynamic imports
- Backward Compatible - Works as a Capacitor plugin too
``bash`
npm install capacitor-biometric-authenticationor
yarn add capacitor-biometric-authentication
`javascript
import BiometricAuth from 'capacitor-biometric-authentication';
// Check availability
const isAvailable = await BiometricAuth.isAvailable();
// Authenticate
const result = await BiometricAuth.authenticate({
reason: 'Please authenticate to continue',
});
if (result.success) {
console.log('Authentication successful!');
}
`
---
This section provides step-by-step instructions for integrating this plugin into a production Capacitor app.
- Node.js 20+
- Capacitor 8.x
- For iOS: Xcode 15+, CocoaPods
- For Android: Android Studio, JDK 17
`bash`
npm install capacitor-biometric-authentication
`bash`
npx cap sync
#### Android Configuration
Minimum Requirements:
- minSdkVersion: 23 (Android 6.0)compileSdkVersion
- : 35
- Java 17
The plugin automatically includes required permissions in its AndroidManifest.xml:
`xml`
Verify Gradle Settings (android/app/build.gradle):
`groovy
android {
compileSdkVersion 35
defaultConfig {
minSdkVersion 23
targetSdkVersion 35
}
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
}
`
#### iOS Configuration
Minimum Requirements:
- iOS 13.0+
- Swift 5.1+
Required Info.plist Entry:
Add to ios/App/App/Info.plist:
`xml`
Note: This key is required for Face ID devices. Without it, your app will crash when attempting Face ID authentication.
#### Web Configuration
Requirements:
- HTTPS (or localhost for development)
- Browser with WebAuthn support (Chrome 67+, Safari 14+, Firefox 60+, Edge 79+)
- Platform authenticator (TouchID, Windows Hello, etc.)
Development:
`bash`
npm run dev # localhost works without HTTPS
Production:
Ensure your site uses HTTPS. WebAuthn will not work on non-secure origins.
`typescript
import BiometricAuth from 'capacitor-biometric-authentication';
// Check if biometrics are available
const available = await BiometricAuth.isAvailable();
if (available) {
// Configure session duration (in seconds)
BiometricAuth.configure({
sessionDuration: 3600, // 1 hour
});
// Authenticate
const result = await BiometricAuth.authenticate({
reason: 'Authenticate to access your account',
fallbackTitle: 'Use Passcode',
});
if (result.success) {
console.log('Authenticated!');
} else {
console.error('Auth failed:', result.error?.message);
}
}
`
Web:
`bash`
npm run build
npm run preview
Android:
`bash`
npx cap sync android
npx cap run androidor open in Android Studio:
npx cap open android
iOS:
`bash`
npx cap sync ios
cd ios && pod install && cd ..
npx cap run iosor open in Xcode:
npx cap open ios
---
`jsx
import { useState, useEffect } from 'react';
import BiometricAuth from 'capacitor-biometric-authentication';
function SecureComponent() {
const [isAuthenticated, setIsAuthenticated] = useState(false);
useEffect(() => {
const unsubscribe = BiometricAuth.subscribe((state) => {
setIsAuthenticated(state.isAuthenticated);
});
return unsubscribe;
}, []);
const handleLogin = async () => {
const result = await BiometricAuth.authenticate({
reason: 'Access your account',
});
if (!result.success) console.error('Auth failed:', result.error);
};
return isAuthenticated ? (
$3
`vue
v-if="!isAuthenticated"
@click="authenticate"
>
Login with Biometrics
Welcome back!
`$3
`html
`---
API Reference
$3
| Method | Description |
| -------------------------- | ------------------------------------ |
|
isAvailable() | Check if biometric auth is available |
| getSupportedBiometrics() | Get available biometric types |
| authenticate(options?) | Perform authentication |
| deleteCredentials() | Clear stored credentials |
| configure(config) | Set plugin configuration |
| logout() | Clear authentication session |$3
| Method | Description |
| --------------------- | -------------------------------- |
|
subscribe(callback) | Subscribe to auth state changes |
| getState() | Get current auth state |
| isAuthenticated() | Check if currently authenticated |$3
| Method | Description |
| ------------------------------------------- | --------------------------- |
|
requireAuthentication(callback, options?) | Execute callback after auth |
| withAuthentication(callback, options?) | Wrap operation with auth |$3
`typescript
BiometricAuth.configure({
sessionDuration: 3600, // Session duration in SECONDS (default: 300)
debug: false, // Enable debug logging
});
`$3
`typescript
await BiometricAuth.authenticate({
reason: 'Authentication Required', // Displayed to user
title: 'Biometric Login', // Android dialog title
subtitle: 'Log in to your account', // Android dialog subtitle
fallbackTitle: 'Use Passcode', // Fallback button text
cancelTitle: 'Cancel', // Cancel button text
disableDeviceCredential: false, // Disable passcode fallback
maxAttempts: 3, // Max failed attempts before lockout
saveCredentials: true, // Store credentials for future use
});
`---
Platform Support
| Platform | Technology | Min Version | Status |
| ------------------ | ------------------ | ----------- | ------ |
| Web | WebAuthn API | Chrome 67+ | ✅ |
| iOS | Touch ID / Face ID | iOS 13.0 | ✅ |
| Android | BiometricPrompt | API 23 | ✅ |
| Electron (macOS) | Touch ID | - | ✅ |
| Electron (Windows) | Windows Hello | Windows 10 | ✅ |
$3
- Chrome/Edge 67+ (Windows Hello, Touch ID)
- Safari 14+ (Touch ID, Face ID)
- Firefox 60+ (Windows Hello)
$3
The plugin supports Windows Hello on Electron for Windows platforms. When running on Windows (win32), the ElectronAdapter automatically uses the WebAuthn API to interface with Windows Hello.
Requirements:
- Windows 10 or later
- Windows Hello configured in Windows Settings
- Electron with WebAuthn support
Usage: The same API works across all platforms:
`javascript
// Works on macOS (Touch ID) and Windows (Windows Hello)
const result = await BiometricAuth.authenticate({
reason: 'Authenticate with Windows Hello',
});
`---
Error Handling
`typescript
import BiometricAuth, {
BiometricErrorCode,
} from 'capacitor-biometric-authentication';const result = await BiometricAuth.authenticate();
if (!result.success) {
switch (result.error?.code) {
case BiometricErrorCode.USER_CANCELLED:
console.log('User cancelled');
break;
case BiometricErrorCode.AUTHENTICATION_FAILED:
console.log('Biometric not recognized');
break;
case BiometricErrorCode.BIOMETRIC_UNAVAILABLE:
console.log('Biometric not available');
break;
case BiometricErrorCode.LOCKOUT:
console.log('Too many failed attempts');
break;
case BiometricErrorCode.NOT_ENROLLED:
console.log('No biometrics enrolled');
break;
default:
console.log('Unknown error:', result.error?.message);
}
}
`---
Troubleshooting
For build failures and common integration issues, see the comprehensive Troubleshooting Guide.
Common issues covered:
- Android Gradle/SDK version mismatches
- iOS Info.plist missing entries
- Pod installation failures
- WebAuthn HTTPS requirements
- Plugin registration issues
---
Development
`bash
Install dependencies
yarn installBuild plugin
yarn buildWatch mode
yarn watchLint & format
yarn lint
yarn prettierTest in example app
cd example
yarn install
yarn dev # Web development
yarn cap:sync # Sync native platforms
yarn cap:ios:run # Run on iOS
yarn cap:android:run # Run on Android
`$3
`
├── src/ # TypeScript source
│ ├── definitions.ts # API interfaces
│ ├── index.ts # Plugin entry
│ ├── web.ts # Web implementation
│ ├── core/ # Core logic
│ ├── adapters/ # Platform adapters
│ └── utils/ # Utilities
├── android/ # Android native (BiometricPrompt)
├── ios/ # iOS native (LocalAuthentication)
├── example/ # React example app
└── docs/ # Documentation
`---
Plugin Metadata
| Property | Value |
| ----------------- | --------------------------------------- |
| Package Name |
capacitor-biometric-authentication |
| Plugin ID | BiometricAuth |
| Android Package | com.aoneahsan.capacitor.biometricauth |
| iOS Class | BiometricAuthPlugin |
| Capacitor Version | 8.x |---
Documentation
docs/`:- Installation Guide
- Quick Start
- Platform Guides - iOS, Android, Web
- API Reference
- FAQ
See Contributing Guide for details.
- Troubleshooting Guide
- GitHub Issues
- Email
See CHANGELOG.md for release history.
MIT © Ahsan Mahmood