@sentinel-password/react

React hook for password validation using @sentinel-password/core. Provides debounced validation with full TypeScript support.

Documentation | Interactive Playground | API Reference

Features

• usePasswordValidator hook - Debounced password validation with configurable delay
• TypeScript-First - Full type safety with strict mode
• Lightweight - Minimal wrapper around @sentinel-password/core
• React 18 & 19 - Supports both React 18 and 19

Installation

@sentinel-password/core is a regular dependency of this package (not a peer), so installing @sentinel-password/react automatically pulls in core. You only need to add it explicitly if you're importing from core directly elsewhere in your app.

npm install @sentinel-password/react
# or
pnpm add @sentinel-password/react
# or
yarn add @sentinel-password/react

Peer dependencies: React 18 or 19 — bring your own.

Quick Start

import { usePasswordValidator } from '@sentinel-password/react'

function PasswordForm() {
  const { password, setPassword, result, isValidating } = usePasswordValidator({
    debounceMs: 300,
    minLength: 10,
    requireUppercase: true,
  })

  return (
    <div>
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Enter password"
      />
      {isValidating && <span>Validating...</span>}
      {result && (
        <div>
          <p>Strength: {result.strength}</p>
          {result.feedback.suggestions.map((s, i) => (
            <p key={i}>{s}</p>
          ))}
        </div>
      )}
    </div>
  )
}

API

usePasswordValidator(options?)

Returns an object with:

| Property | Type | Description | |----------|------|-------------| | password | string | Current password value | | setPassword | (password: string) => void | Update the password. Whether validation also fires depends on debounceMs / validateOnChange — see those rows below. In manual mode (debounceMs: 0 + validateOnChange: false) this only updates state; call validate() to evaluate. | | result | ValidationResult \| undefined | Validation result (undefined until first validation) | | isValidating | boolean | Whether validation is in progress (during debounce) | | validate | () => void | Manually trigger validation | | reset | () => void | Reset password and validation state |

Options

Extends all @sentinel-password/core options plus:

| Option | Type | Default | Description | |--------|------|---------|-------------| | debounceMs | number | 300 | Debounce delay in ms (0 to disable) | | initialPassword | string | '' | Seed value for the hook's password state. Use this together with validateOnMount to validate a pre-filled value (e.g. edit-profile flows) on first render. The input stays fully controlled by setPassword afterwards. | | validateOnMount | boolean | false | Validate the seed value (see initialPassword) once on mount. Skips empty values, so it's a no-op when initialPassword is empty or omitted. | | validateOnChange | boolean | false | Only matters when debounceMs === 0: true validates synchronously on every change, false disables automatic validation (call validate() manually). With the default debounceMs > 0, debounced validation runs on every change regardless of this flag. |

Related Packages

• @sentinel-password/core - Core validation engine (zero dependencies)
• @sentinel-password/react-components - Accessible, headless React components

License

MIT © Aleksei Kankov