@sentinel-password/react

@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