Secure PIN code screen with biometric authentication for React Native (JS-only, New Architecture compatible)
npm install @kruglyanski/react-native-secure-pin-codeReact Native Secure PIN Code
A secure, customizable PIN code solution for React Native with optional biometric authentication and built-in lockout protection.
This library provides:
secure PIN storage
automatic lockout after failed attempts
optional Face ID / Touch ID authentication
a ready-to-use PIN screen
a small, stable, forward-compatible API
The library is designed to be safe by default and suitable for production use.
Installation
Install the package:
yarn add @kruglyanski/react-native-secure-pin-code
or
npm install @kruglyanski/react-native-secure-pin-code
Install required native dependencies:
yarn add react-native-keychain react-native-biometrics react-native-device-info
Then install iOS pods:
cd ios && pod install
A secure, customizable PIN code solution for React Native with biometric authentication support.
This library provides a ready-to-use PIN screen, secure storage, lockout protection, and biometric login, while allowing full control over UI customization.
---
yarn add @kruglyanski/react-native-secure-pin-code
or
npm install @kruglyanski/react-native-secure-pin-code
Install required native dependencies:
yarn add react-native-keychain react-native-biometrics react-native-device-info
Then install iOS pods:
cd ios && pod install
---
- Secure PIN storage using native keychain
- Configurable PIN length (4–8 digits)
- Lockout after multiple failed attempts
- Biometric authentication (Face ID / Touch ID / Android Biometrics)
- Fully customizable UI
- Clean Provider + Hook API
- Works with the New Architecture
- Written in TypeScript
---
⚠️ SecurePinProvider is required
Both:
- useSecurePin
- SecurePinScreen
MUST be rendered inside SecurePinProvider.
The hook and the screen will NOT work outside the provider.
---
The provider is responsible for:
- PIN storage
- Attempt counting
- Lock timers
- Biometric authentication
- Global PIN state
- children
Your application content.
- maxAttempts (optional)
Maximum number of allowed failed PIN attempts before lock.
Default: 3
- lockDurationSec (optional)
Lock duration in seconds after exceeding max attempts.
Default: 30
- biometryPromptText (optional)
Text shown in biometric authentication prompt.
- biometryPromptCancelText (optional)
Cancel button text in biometric prompt.
- showBiometrics (optional)
Enables biometric login availability.
Default: true
---
The hook provides access to PIN state and actions.
- hasPin
Indicates whether a PIN is already set.
true, false, or null while loading.
- isLocked
Whether PIN input is currently locked.
- lockUntil
Timestamp (ms) when the lock will be released, or null.
- attemptsLeft
Number of remaining attempts before lock.
- setPin(pin)
Saves a new PIN securely.
- checkPin(pin)
Verifies the entered PIN.
- loginWithBiometrics()
Attempts biometric authentication.
- deletePin()
Removes the stored PIN.
---
A fully controlled UI component that handles:
- PIN creation
- PIN confirmation
- PIN verification
- Lock state UI
- Error and status messages
#### Behavior
- pinLength
Length of the PIN.
Supported values: 4–8
- onSuccess
Called when PIN is successfully created or verified.
- onPressForgetPin
Required callback for "Forgot PIN" action.
- allowFontScaling
Enables or disables font scaling.
Default: true
---
#### Text customization
- titleSet
Title shown when creating a PIN.
- titleEnter
Title shown when entering a PIN.
- enterMessage
Message shown on PIN entry screen.
- createMessage
Message shown on PIN creation screen.
- confirmMessage
Message shown on PIN confirmation screen.
- doNotMatchMessage
Message shown when PINs do not match.
- lockedMessage
Message shown when input is locked.
- wrongPinMessage
Function returning message when PIN is incorrect.
Receives attemptsLeft.
- textDescriptionLockedPage
Main lock screen description.
- textSubDescriptionLockedPage
Secondary lock screen description.
- exitButtonText
Text for exit / logout button on lock screen.
---
#### Style customization
- containerStyle
- titleStyle
- subtitleStyle
- lockTextStyle
- keyPadStyle
- keyStyle
- keyTextStyle
All style props accept standard React Native style objects.
---
#### UI customization
- eraseComponent
Custom component for the erase (backspace) button.
---
This library relies on the following native dependencies:
- react-native-keychain
- react-native-biometrics
- react-native-device-info
They must be installed and properly linked in your project.
---
- iOS
- Android
Supports the New Architecture.
---
MIT © Roman Kruglyanski