passwise
Version:
A customizable React password strength checker library
218 lines (166 loc) • 6.74 kB
Markdown
# Passwise
A highly customizable React component library for password strength checking and validation.
[](https://www.npmjs.com/package/passwise)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
## Features
- 🔒 **Robust Security Analysis**: Uses the battle-tested [zxcvbn](https://github.com/dropbox/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
```bash
# npm
npm install passwise
# yarn
yarn add passwise
# pnpm
pnpm add passwise
```
## Usage
### Basic Example
```tsx
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
```tsx
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)
```tsx
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
```typescript
interface PasswordPolicy {
minLength?: number;
maxLength?: number;
mustContain?: {
lowercase?: boolean;
uppercase?: boolean;
number?: boolean;
symbol?: boolean;
};
}
```
### PasswordStrengthResult Object
```typescript
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