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