react-native-secure-gate 🛡️

A premium, hardware-accelerated biometric (FaceID/TouchID) prompt wrapper and secure passcode shield overlay for React Native and Expo. It completely masks your app's content with a customizable overlay, triggers native biometrics, and falls back to a gorgeous PIN-pad passcode overlay when necessary.

Features

• 🔒 Privacy Shield: Completely overlays sensitive app screens so contents are hidden when returning from background states.
• 🤖 Expo & Bare Biometrics: Wraps expo-local-authentication dynamically to request FaceID/TouchID/Fingerprint scans.
• 🔢 Secure Passcode Keypad: Offers a full-featured numeric entry pad with automatic passcode length matching.
• 🎨 Modern Themes: Choose between dark, light, or glass (glassmorphic translucent blur) visual backdrops.
• 📳 Shake-to-Error Feedback: Triggers smooth, physical error shake translations when biometric verification or passcodes fail.
• 📦 Fallback Ready: Gracefully auto-degrades to PIN passcode mode if biometrics hardware is absent or not enrolled.

Installation

npm install react-native-secure-gate expo-local-authentication

or

yarn add react-native-secure-gate expo-local-authentication

⚠️ Note for Bare React Native Projects (Non-Expo)

If you are integrating this into a bare React Native project, you must also install the core Expo module runtime to support biometrics:

npm install expo expo-modules-core
# For iOS, remember to update cocoapods
cd ios && pod install

Usage

1. Simple Biometric Overlay with PIN Fallback

Overlay the screen with a glassmorphic security wall, requesting FaceID/TouchID on start, and falling back to PIN passcode 1234 on failure:

import React, { useState } from 'react';
import { View, StyleSheet, Text, Button } from 'react-native';
import { SecureGate } from 'react-native-secure-gate';

export default function SensitiveScreen() {
  const [isLocked, setIsLocked] = useState(true);

  return (
    <View style={styles.container}>
      <Text style={styles.text}>Welcome to your secret vault!</Text>
      <Button title="Lock App" onPress={() => setIsLocked(true)} />

      <SecureGate
        isActive={isLocked}
        fallbackPin="1234"
        theme="glass"
        title="Vault Access"
        subtitle="Please verify your identity to access vault files"
        onSuccess={() => {
          setIsLocked(false);
          console.log('App unlocked successfully!');
        }}
        onFailure={(error) => {
          console.log('Authentication failed: ', error);
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    backgroundColor: '#F8FAFC',
  },
  text: {
    fontSize: 18,
    color: '#0F172A',
    marginBottom: 20,
  },
});

API Properties

<SecureGate>

| Parameter | Type | Default | Description | |---|---|---|---| | isActive | boolean | (Required) | Toggles the overlay active visibility state. | | onSuccess | () => void | (Required) | Callback fired when biometric scan or PIN entry succeeds. | | onFailure | (error: string) => void | undefined | Callback fired on scan failures or invalid passcode entry. | | fallbackPin | string | undefined | The passcode string to enable fallback PIN input pad. | | pinLength | number | 4 | Number of digit inputs required to validate fallback PIN. | | theme | 'dark' \| 'light' \| 'glass' | 'dark' | Visual layout style theme. | | title | string | 'App Locked' | Main lock screen header text. | | subtitle | string | 'Authenticate...' | Header explanation subtitle text. | | logo | React.ReactNode | (Default Shield) | Custom vector logo element at the top. | | promptText | string | 'Unlock with Biometrics' | Prompt title shown below scanning icons. | | autoAuthenticate | boolean | true | Auto-triggers native OS biometric prompt on mount. | | onHapticTrigger | (type: 'success' \| 'error' \| 'selection') => void | undefined | Optional callback to trigger native haptic vibrations. | | style | StyleProp<ViewStyle> | undefined | Styling overrides for top-level overlay container. |

License

MIT