@sentinel-password/react-components

@sentinel-password/react-components

Accessible, headless React components for password validation, built on top of @sentinel-password/core.

Documentation | Interactive Playground | API Reference

Features

• Headless & Unstyled - Bring your own styles
• Designed for WCAG 2.1 AAA - Semantic HTML, ARIA live region, full keyboard support, useId()-linked label. Page-level conformance depends on the consumer's CSS (contrast) and surrounding markup — see Accessibility below.
• Keyboard Navigation - Complete keyboard support
• TypeScript - Full type safety
• Lightweight - Minimal bundle size
• Flexible - Controlled and uncontrolled modes
• 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-components automatically pulls in core. You only need to add core explicitly if you're importing from it directly elsewhere in your app.

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

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

Quick Start

import { PasswordInput } from '@sentinel-password/react-components'

function MyForm() {
  return (
    <form>
      <PasswordInput
        label="Password"
        onValidationChange={(result) => {
          console.log('Valid:', result.valid)
          console.log('Strength:', result.strength)
        }}
      />
    </form>
  )
}

API Reference

PasswordInput

A headless password input component with built-in validation.

<PasswordInput
  label="Password"
  description="Enter a strong password"
  onValidationChange={(result) => console.log(result)}
  onChange={(value) => console.log(value)}
  showPassword={false}
  onShowPasswordChange={(show) => console.log(show)}
  validateOnMount={false}
  debounceMs={300}
/>

Props

Prop	Type	Default	Description
label	string	required	Accessible label rendered as <label>
description	string	—	Helper text linked via aria-describedby
value	string	—	Controlled value. Any defined value flips the component to controlled mode — see the Controlled vs Uncontrolled rules.
defaultValue	string	—	Uncontrolled initial value. Silently ignored if value is defined.
onChange	(value: string) => void	—	Fired with the new string value (not the event)
onValidationChange	(result: ValidationResult) => void	—	Fired whenever validation completes
onShowPasswordChange	(show: boolean) => void	—	Fired when the show/hide toggle changes state
showPassword	boolean	uncontrolled	Controlled show/hide state — omit for uncontrolled toggle
validateOnMount	boolean	false	Validate the initial value once on mount — only if value/defaultValue is non-empty. Uses the debounced path; set debounceMs: 0 for synchronous mount validation.
validateOnChange	boolean	true	Validate on every change (debounced). Set to false to disable change-driven validation.
debounceMs	number	300	Debounce delay in milliseconds. 0 validates synchronously.
showValidationMessages	boolean	true	Render the validation messages <div role="alert">. Set to false to suppress the messages and render your own.
showToggleButton	boolean	true	Render the show/hide password button. Set to false to suppress (e.g., for a localized custom toggle).
validatorOptions	ValidatorOptions	undefined	Forwarded to every internal validatePassword(...) call. Covers minLength, requireUppercase, personalInfo, plus the v1.2.0 i18n options messages and formatMessage. Nested rather than spread because the prop type already extends React.InputHTMLAttributes<HTMLInputElement> (which defines minLength / maxLength as HTML attrs). Memoize this object if it contains closures — see the i18n guide.
toggleShowText	string	'Show'	Visible button text when the password is hidden
toggleHideText	string	'Hide'	Visible button text when the password is visible
toggleShowLabel	string	'Show password'	aria-label when hidden
toggleHideLabel	string	'Hide password'	aria-label when visible
containerClassName	string	''	Class on the outer <div> wrapper
labelClassName	string	''	Class on <label>
descriptionClassName	string	''	Class on the description <div>
inputWrapperClassName	string	''	Class on the <input> + toggle wrapper
toggleButtonClassName	string	''	Class on the show/hide <button>
validationClassName	string	''	Class on the validation messages <div>
className (and other standard input attrs)	—	—	Forwarded to the underlying <input> (className, name, placeholder, autoFocus, etc.). See the "reserved" list below for the exceptions.

Most standard HTML input attributes are forwarded to the underlying <input> — for example name, placeholder, className, style, autoFocus, required, minLength, maxLength, pattern, inputMode, onFocus, onBlur, and data-*.

A handful are reserved by the component for its a11y and controlled-state internals — passing them is harmless but has no effect at runtime:

• id — generated via useId() so the <label> can be associated correctly
• aria-describedby / aria-invalid — managed for validation feedback
• autoComplete — hardcoded to "new-password"
• ref — not forwarded (the component is not wrapped in React.forwardRef)
• type — toggled internally between "password" and "text"; omitted from the props type
• onChange — replaced with the (value: string) => void signature documented above

onKeyDown is wrapped (the component handles Escape to clear the input, then calls your handler for all keys) rather than overridden.

See the API reference for the full table and the controlled-vs-uncontrolled rules.

Accessibility

The component is designed to meet WCAG 2.1 AAA criteria when integrated correctly. It provides:

• Semantic HTML (<label htmlFor> linked to the input via useId())
• ARIA attributes managed by the component: aria-invalid (true/omitted), aria-describedby, aria-pressed on the toggle button
• A live region (role="alert" aria-live="polite" aria-atomic="true") that mounts only when there's feedback to announce
• Keyboard support: Tab between input and toggle, Escape to clear the input, Space/Enter on the toggle button
• Focus management for the input and toggle

The consumer is responsible for:

• Color contrast — the component is headless, so CSS is yours. WCAG AAA requires 7:1 for normal text and 4.5:1 for large text.
• Surrounding markup — heading structure, landmarks, form semantics, and overall page conformance.
• Reduced-motion / forced-colors / focus-visible — these depend on your stylesheet.
• Localization of toggle text — covered by toggleShowText / toggleHideText / toggleShowLabel / toggleHideLabel props (see below).

Internationalization

• Validator messages — pass validatorOptions to forward messages / formatMessage (or any other ValidatorOptions field) into the component's underlying validatePassword calls. See the i18n guide for full examples.
• Toggle button text — toggleShowText / toggleHideText set the visible button label; toggleShowLabel / toggleHideLabel set the aria-label. Defaults are 'Show' / 'Hide' / 'Show password' / 'Hide password'.

Related Packages

• @sentinel-password/core - Core validation engine (zero dependencies)
• @sentinel-password/react - React hook for password validation

License

MIT © Aleksei Kankov