passwise

Passwise

A highly customizable React component library for password strength checking and validation.

Features

• 🔒 Robust Security Analysis: Uses the battle-tested zxcvbn library originally created by Dropbox for password strength estimation
• 🎨 Fully Customizable UI: Light and dark theme support with further customization options
• 🧩 Headless Option: Use the usePasswordStrength hook for complete UI control
• 📏 Custom Password Policies: Define your own password requirements
• 🔄 Real-time Feedback: Strength meter, validation state, and improvement suggestions
• 📦 Modern Bundle: Tree-shakable ESM and CommonJS builds
• 📝 Type-safe: Written in TypeScript with comprehensive type definitions
• 🎯 Optional TailwindCSS: Styling with Tailwind, but also works without it

Installation

# npm
npm install passwise

# yarn
yarn add passwise

# pnpm
pnpm add passwise

Usage

Basic Example

import React, { useState } from "react";
import { PasswordStrengthMeter } from "passwise";

function PasswordForm() {
  const [password, setPassword] = useState("");

  return (
    <div>
      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
      />

      <PasswordStrengthMeter
        password={password}
        theme="dark"
        policy={{
          minLength: 8,
          mustContain: {
            lowercase: true,
            uppercase: true,
            number: true,
            symbol: true,
          },
        }}
      />
    </div>
  );
}

With Custom Password Policy

import React, { useState } from 'react';
import { PasswordStrengthMeter } from 'passwise';

function PasswordFormWithPolicy() {
  const [password, setPassword] = useState('');

  // Define a custom password policy
  const passwordPolicy = {
    minLength: 8,
    mustContain: {
      lowercase: true,
      uppercase: true,
      number: true,
      symbol: true
    }
  };

  return (

      <input
        id="password"
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
      />

    <PasswordStrengthMeter
        password={password}
        theme="dark"
        policy={passwordPolicy}
      />


  );
}

Using the Hook (Headless)

import React, { useState } from 'react';
import { usePasswordStrength } from 'passwise';

function CustomPasswordUI() {
  const [password, setPassword] = useState('');

  // Use the headless hook
  const strengthResult = usePasswordStrength({
    password,
    policy: {
      minLength: 10
    }
  });

  // Create your own UI based on the strength result
  return (

      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
      />


        Strength score: {strengthResult.score}/4
        Rating: {strengthResult.label}

        {strengthResult.feedback.warning && (
          Warning: {strengthResult.feedback.warning}
        )}

        {strengthResult.feedback.suggestions.length > 0 && (

            {strengthResult.feedback.suggestions.map((suggestion, i) => (
              {suggestion}
            ))}

        )}


  );
}

API Reference

PasswordStrengthMeter Props

Prop	Type	Default	Description
password	string	required	The password to evaluate
theme	'light' | 'dark'	'light'	UI theme
className	string	''	Additional CSS classes
showLabels	boolean	true	Show strength labels
showBar	boolean	true	Show strength bar
showSuggestions	boolean	true	Show validation and suggestions
scoreWords	[string, string, string, string, string]	['Very Weak', 'Weak', 'Fair', 'Good', 'Strong']	Custom labels for each strength level
policy	PasswordPolicy	undefined	Custom password requirements
barOnly	boolean	false	Show only the strength bar
onChange	(result: PasswordStrengthResult) => void	undefined	Callback when strength changes

PasswordPolicy Object

interface PasswordPolicy {
  minLength?: number;
  maxLength?: number;
  mustContain?: {
    lowercase?: boolean;
    uppercase?: boolean;
    number?: boolean;
    symbol?: boolean;
  };
}

PasswordStrengthResult Object

interface PasswordStrengthResult {
  score: 0 | 1 | 2 | 3 | 4; // 0 = weakest, 4 = strongest
  label: "Very Weak" | "Weak" | "Fair" | "Good" | "Strong";
  feedback: {
    suggestions: string[];
    warning: string | null;
  };
  passwordLength: number;
  validations: PasswordValidationResult[];
  meetsPolicy: boolean;
}

Styling and Customization

Using TailwindCSS

This library provides default styling using TailwindCSS. The classes are prefixed with pw- to avoid conflicts with your application's own Tailwind classes.

Without TailwindCSS

If you're not using TailwindCSS, the components will still work, but you might want to provide your own styling via the className prop and CSS.

License

MIT