# check-password-strength

> A NPM Password strength checker based from Javascript RegExp. Check passphrase if it's "Too weak", "Weak", "Medium" or "Strong"

Latest version **3.0.0** (published 2025-01-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install check-password-strength
pnpm add check-password-strength
yarn add check-password-strength
bun add check-password-strength
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2025-01-20 |
| First published | 2020-01-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 14.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 191 |
| Author | deanilvincent |
| Maintainers | dvincent333 |
| Keywords | npm, password, strength, checker, check password strength, password strength checker, strength checker, password checker, password checker strength, strength password checker, check-password-strength, password-strength-checker, strength-checker, password-checker, password-checker-strength, strength-password-checker, pass-strength |

## Links

- npm: https://www.npmjs.com/package/check-password-strength
- Repository: https://github.com/deanilvincent/check-password-strength
- Homepage: https://github.com/deanilvincent/check-password-strength#readme
- Issues: https://github.com/deanilvincent/check-password-strength/issues
- npm.io page: https://npm.io/package/check-password-strength

## Dependencies (1)

- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) ^5.0.0

## Recent versions

- 3.0.0 (latest) — 2025-01-20
- 2.0.10 — 2024-03-07
- 2.0.9 — 2024-03-06
- 2.0.8 — 2024-03-04
- 2.0.7 — 2022-07-25
- 2.0.6 — 2022-07-25
- 2.0.5 — 2022-03-11
- 2.0.4 — 2022-02-09
- 2.0.3 — 2021-04-25
- 2.0.2 — 2021-03-02
- 2.0.1 — 2021-03-02
- 2.0.0 — 2021-03-02
- 1.0.15 — 2020-09-21
- 1.0.14 — 2020-09-21
- 1.0.13 — 2020-09-16
- … 12 more at https://npm.io/package/check-password-strength/versions

## README

# Overview

A simple way to check that password strength of a certain passphrase. The library is fully typed.

[![Build status](https://dev.azure.com/dv-github-repos/check-password-strength/_apis/build/status/check-password-strength-CI)](https://dev.azure.com/dv-github-repos/check-password-strength/_build/latest?definitionId=12) 

[![npm](https://img.shields.io/npm/dm/check-password-strength.svg)](https://img.shields.io/npm/dm/check-password-strength.svg) [![Downloads](https://img.shields.io/npm/dt/check-password-strength.svg)](https://img.shields.io/npm/dt/check-password-strength.svg)

[DEMO 1](https://svelte.dev/repl/b5bf5871c99742e584da244b4bfeac92?version=3.44.3) by [@Ennoriel](https://github.com/Ennoriel)

[DEMO 2](https://check-password-strength.netlify.app/)

## Installation

### Install via Package Manager

`npm i check-password-strength --save`

### Install via Browser Script Tag using [UNPKG](https://unpkg.com/)

```html
<script src="https://unpkg.com/check-password-strength/dist/umd.cjs"></script>
<script type="text/javascript">
    const passwordStrength = checkPasswordStrength.passwordStrength('pwd123').value; // 'Weak'
</script>
```

## Setup & Basic Usage

```javascript
const { passwordStrength } = require('check-password-strength')
// OR
import { passwordStrength } from 'check-password-strength'

console.log(passwordStrength('asdfasdf').value)
// Too weak (It will return Too weak if the value doesn't match the Weak conditions)

console.log(passwordStrength('asdf1234').value)
// Weak

console.log(passwordStrength('Asd1234!').value)
// Medium

console.log(passwordStrength('A@2asdF2020!!*').value)
// Strong
```

## API

### arguments

The `passwordStrength` takes 3 arguments:

- `password` (string): the user password
- `options` (array — optional): an option to override the default complexity required to match your password policy. See below.
- `restrictSymbolsTo` (string — optional): 
  - By default, the `passwordStrength` function checks against all characters except for the 26 Latin lowercase letters, 26 uppercase letters, and 10 digits. This includes OWASP-recommended characters, accented letters, other alphabets, and emojis.
  - If you wish to apply restrictions, you can provide a custom string. This string should consist of unescaped symbol characters, which will be utilized internally in a RegExp expression in the following format: `[${escapeStringRegexp(restrictSymbolsTo)}]`.
  - Additionally, you can import and use the owaspSymbols to limit the symbols to those recommended by OWASP.

**Password Default Options**

The default options can be required:

```javascript
const { defaultOptions } = require("./index");
// OR
import { defaultOptions } from 'check-password-strength'
```

default options:
```javascript
[
  {
    id: 0,
    value: "Too weak",
    minDiversity: 0,
    minLength: 0
  },
  {
    id: 1,
    value: "Weak",
    minDiversity: 2,
    minLength: 8
  },
  {
    id: 2,
    value: "Medium",
    minDiversity: 4,
    minLength: 10
  },
  {
    id: 3,
    value: "Strong",
    minDiversity: 4,
    minLength: 12
  }
]
```

To override the default options, simply pass your custom array as the second argument:

  - id: correspond to the return id attribute.
  - value: correspond to the return value attribute.
  - minDiversity: between 0 and 4, correspond to the minimum of different criterias ('lowercase', 'uppercase', 'symbol', 'number') that should be met to pass the password strength
  - minLength: minimum length of the password that should be met to pass the password strength

**You can use an array containing fewer or more than four items to define the levels of trust.** However, the first element must have both the minDiversity and minLength parameters set to 0. This means that the first element should always represent a "too weak" option.

### Result

The result is an object containing the following values (unless you override the `options`):

| Property | Desc.                                                           |
| -------- | --------------------------------------------------------------- |
| id       | **0** = Too weak, **1** = Weak & **2** = Medium, **3** = Strong |
| value    | Too weak, Weak, Medium & Strong                                 |
| contains | lowercase, uppercase, number and / or symbol                    |
| length   | length of the password                                          |

If you want to translate the value (Too weak → Trop faible), you can translate it based on the return value, or override the `defaultOptions` option, which will be passed back as the function's return value.

## Contribute

Feel free to clone or fork this project:  `https://github.com/deanilvincent/check-password-strength.git`

Contributions & pull requests are welcome!

I'll be glad if you give this project a ★ on [Github](https://github.com/deanilvincent/check-password-strength) :)

## changelog

- v3: allow all symbols by default (any character except the 26 latin lowercase, uppercase letters and 10 digits) & set the default min length to 12 instead of 10
- v2: allow configuration through `options` object
- v1: first version

***

Kudos to [@Ennoriel](https://github.com/Ennoriel) and his efforts for making v2 and v3 possible!

---
_Source: https://npm.io/package/check-password-strength · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
