npm package: @kruglyanski/react-native-secure-pin-code
Description: Secure PIN code screen with biometric authentication for React Native (JS-only, New Architecture compatible)
Latest version: 0.1.1

React 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
# @kruglyanski/react-native-secure-pin-code

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.
---
## 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

---

## Features

- 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

---

## Important Usage Rule

⚠️ **SecurePinProvider is required**

Both:
- `useSecurePin`
- `SecurePinScreen`

**MUST be rendered inside `SecurePinProvider`.**

The hook and the screen will NOT work outside the provider.

---

## SecurePinProvider

The provider is responsible for:
- PIN storage
- Attempt counting
- Lock timers
- Biometric authentication
- Global PIN state

### SecurePinProvider props

- **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`

---

## useSecurePin Hook

The hook provides access to PIN state and actions.

### Returned API description

- **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.

---

## SecurePinScreen

A fully controlled UI component that handles:
- PIN creation
- PIN confirmation
- PIN verification
- Lock state UI
- Error and status messages

### SecurePinScreen props

#### 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.

---

## Dependencies

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.

---

## Platform Support

- iOS
- Android

Supports the New Architecture.

---

## License

MIT © Roman Kruglyanski