Biometric Unlock

A comprehensive solution for securing your Expo application with biometric authentication (Face ID, Touch ID, Fingerprint) or device passcode. Supports full app lock and verification for specific user actions.

Installation

$ cbui-cli install biometricunlock

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

App.tsx

import { BiometricProvider, BiometricLock, useBiometric, useBiometricAction, useBiometricSettings } from '@/crossbuildui/biometricunlock'; // Make sure to have expo-local-authentication and expo-secure-store installed.;

This component depends on expo-local-authentication and expo-secure-store. Make sure they are installed in your project.

Basic Setup

To enable biometric features, wrap your application's root component with BiometricProvider and your main content with BiometricLock. The BiometricProvider manages the state and configuration, while BiometricLock renders the lock screen overlay when needed.

App.tsx

// In your App.tsx or root component
import { BiometricProvider, BiometricLock } from '@/crossbuildui/biometricunlock';
import { View, Text } from 'react-native';

const initialConfig = {
    mode: 'app_lock',
    lockCondition: 'immediately',
    allowDevicePasscode: true,
};

const AppContent = () => {
    // Your main application content goes here
    return (
        <View>
            <Text>Welcome to the App!</Text>
        </View>
    );
};

export default function App() {
    return (
        <BiometricProvider config={initialConfig}>
            <BiometricLock>
                <AppContent />
            </BiometricLock>
        </BiometricProvider>
    );
}

Authentication Modes

The component operates in three modes, configured via the mode property in the config object:

'app_lock': (Default) Secures the entire application. The lock screen is shown on app launch or resume, based on the lockCondition.
'action_verification': Does not lock the app automatically. Use the useBiometricAction hook to trigger authentication for specific, sensitive user actions.
'none': Disables all biometric features. The app is never locked, and authentication calls will succeed without a prompt.

index.tsx

// 1. App Lock Mode (locks the entire app)
<BiometricProvider config={{ mode: 'app_lock', lockCondition: 'immediately' }}>
    <BiometricLock>
        {/* Your App */}
    </BiometricLock>
</BiometricProvider>

// 2. Action Verification Mode (for specific actions)
// Provider config can be 'action_verification' or 'none'
const MySecureComponent = () => {
    const { authenticateAction } = useBiometricAction();

    const handleSensitiveAction = async () => {
        const result = await authenticateAction(async () => {
            // This part runs only after successful authentication
            console.log('Action authorized!');
            return 'Sensitive Data';
        )
    };

    if (result.success) {
      console.log('Received:', result.data);
    } else {
      console.error('Authorization failed:', result.error);
    }

    return <Button onPress={handleSensitiveAction}>Perform Secure Action</Button>;
}

// 3. None (Biometrics disabled)
<BiometricProvider config={{ mode: 'none' }}>
    {/* App content is always visible */}
</BiometricProvider>

Lock Conditions

In 'app_lock' mode, you can define when the app should lock after moving to the background using the lockCondition property:

'immediately': Locks the app as soon as it enters the background.
'after_delay': Locks the app after a specified time. Requires setting lockDelayMinutes.

config.ts

// Lock immediately when app goes to background
const config1 = {
    mode: 'app_lock',
    lockCondition: 'immediately',
};

// Lock 5 minutes after app goes to background
const config2 = {
    mode: 'app_lock',
    lockCondition: 'after_delay',
    lockDelayMinutes: 5,
};

Available Hooks

useBiometric

Accesses the core biometric context. Useful for directly checking lock state or triggering authentication.

useBiometricAction

Provides the authenticateAction function, ideal for the 'action_verification' mode to protect specific functions.

useBiometricSettings

A powerful hook for building a settings screen where users can configure their own biometric preferences (e.g., enabling/disabling the lock, changing the lock condition). It provides functions to safely update the global configuration.

SettingsScreen.tsx

import { useBiometricSettings } from '@/crossbuildui/biometricunlock';

const SettingsScreen = () => {
    const { settings, toggleAppLock, isAppLockEnabled, updateLockCondition } = useBiometricSettings();

    const handleToggleLock = (enabled) => {
        toggleAppLock(enabled);
        if (enabled) {
            // Optionally set a default lock condition
            updateLockCondition('immediately');
        }
    };

    return (
        <View>
            <Text>Enable App Lock</Text>
            <Switch
                value={isAppLockEnabled()}
                onValueChange={handleToggleLock}
            />
            {isAppLockEnabled() && (
            <View>
                {/* Add more settings controls here, e.g., for lock condition */}
            </View>
            )}
        </View>
    );
};

Customizing the Lock Screen

The appearance of the lock screen can be fully customized via the lockScreenConfig object within your main configuration. You can change text, add a logo, and apply custom styles.

App.tsx

import { BiometricLock } from '@/crossbuildui/biometricunlock';
import Icon from 'react-native-vector-icons/MaterialIcons';

const customLockScreenConfig = {
    appName: 'My Secure App',
    unlockButtonText: 'Verify to Continue',
    logo: <Icon name="security" size={48} color="teal" />,
};

<BiometricProvider config={{ ...initialConfig, lockScreenConfig: customLockScreenConfig }}>
    <BiometricLock>
        {/* ... App Content ... */}
    </BiometricLock>
</BiometricProvider>

Props & Types Overview

BiometricProvider Props

PROP	TYPE	DESCRIPTION
`children`	`ReactNode`	The child components, typically the entire app.
`config`	`BiometricUnlockConfig`	The initial configuration for biometric locking.

BiometricLock Props

PROP	TYPE	DESCRIPTION
`children`	`ReactNode`	Content to display when the app is unlocked.
`config`	`Partial<BiometricUnlockConfig>`	Optional config overrides for this specific lock instance.
`onAuthSuccess`	`(result: AuthResult) => void`	Callback fired on successful authentication.
`onAuthFailed`	`(error: string) => void`	Callback fired on failed authentication.
`onAuthCancelled`	`() => void`	Callback fired when the user cancels the auth prompt.
`onLockStateChange`	`(isLocked: boolean) => void`	Callback fired when the lock state changes.
`isVisible`	`boolean`	Controls the visibility of the component and its lock screen. Default: `true`.
`style`	`StyleProp<ViewStyle>`	Custom styles for the component container.

BiometricUnlockConfig Type

KEY	TYPE	DESCRIPTION
`mode`	`AuthMode`	Authentication mode ('app_lock', 'action_verification', 'none').
`lockCondition`	`LockCondition`	When to lock the app ('immediately', 'after_delay').
`lockDelayMinutes`	`number`	Delay in minutes before locking if condition is 'after_delay'.
`autoShowOnAppOpen`	`boolean`	Show auth prompt automatically on app open if locked.
`allowDevicePasscode`	`boolean`	Allow device passcode as a fallback for biometrics.
`promptTitle`	`string`	Custom title for the native authentication prompt.
`lockScreenConfig`	`LockScreenConfig`	Configuration object for the custom lock screen UI.

Accessibility

The component leverages the native biometric authentication prompts provided by iOS and Android, which are designed to be accessible. The custom lock screen elements are standard React Native components that support accessibility props.

Dropdown