zxcvbn-ts
Guide
Demo
Changelog
GitHub
Guide
Demo
Changelog
GitHub
  • Guide

    • Introduction
    • Getting started
    • Options
    • Languages
    • Filtering custom words
    • Matcher
    • Pwned matcher
    • Lazy loading
    • Best Practices
    • Examples
    • Framework examples
    • TypeScript
    • Comparison
    • Migration
  • Demo

    • Demo

TypeScript

All packages are written in TypeScript and ship their own type definitions, so there is nothing extra to install. The types are exported from @zxcvbn-ts/core; import them with import type so they don't end up in your bundle.

import { ZxcvbnFactory } from '@zxcvbn-ts/core'
import type { OptionsType, ZxcvbnResult } from '@zxcvbn-ts/core'

const options: OptionsType = {
  // ...
}
const zxcvbn = new ZxcvbnFactory(options)

const result: ZxcvbnResult = zxcvbn.check(password)

Options and result

TypeDescription
OptionsTypeThe first parameter of ZxcvbnFactory, see options.
TranslationKeysThe shape of the translations option, see translation keys.
TimeEstimationValuesThe shape of the timeEstimationValues option.
OptionsDictionaryThe shape of the dictionary option: Record<string, (string | number)[]>.
OptionsGraphThe shape of the graphs option.
OptionsL33tTableThe shape of the l33tTable option.
ZxcvbnResultThe return value of check and the resolved value of checkAsync, see output.
Score0 | 1 | 2 | 3 | 4
FeedbackType{ warning: string | null, suggestions: string[] }, the feedback of the result.
CrackTimesThe crackTimes of the result, one CrackTime ({ base, seconds, display }) per attack scenario.

Matches

result.sequence is an array of MatchExtended, a union of the match types of the built-in matchers. Each has the base properties of Match (pattern, token, i, j) and properties of its own. Check pattern to narrow the type:

import type { DateMatch, MatchExtended } from '@zxcvbn-ts/core'

const isDateMatch = (match: MatchExtended): match is DateMatch =>
  match.pattern === 'date'

const dates = result.sequence.filter(isDateMatch).map((match) => match.year)
TypeDescription
MatchThe base properties every match has.
DictionaryMatch, L33tMatch, SpatialMatch, RepeatMatch, SequenceMatch, WordSequenceMatch, RegexMatch, DateMatch, BruteForceMatch, SeparatorMatchThe matches of the built-in matchers.
MatchExtendedThe union of all of them; it also includes Match, so matches of custom matchers fit in.
MatchEstimatedA MatchExtended after scoring, with guesses and guessesLog10.
PatternThe pattern names of the built-in matchers, or any string for custom matchers.

Custom matchers

These are the types for writing your own custom matcher:

TypeDescription
MatcherThe object you pass in the second parameter of ZxcvbnFactory: { Matching, feedback, scoring }.
MatcherBaseClassThe abstract class the Matching class has to extend. It gets the Options instance as this.options.
MatchOptionsThe parameter of match: password, omniMatch (to run the other matchers, like the repeat matcher does) and userInputsOptions.
MatcherConstructorThe type of Matching.
DefaultFeedbackFunctionThe type of feedback.
DefaultScoringFunctionThe type of scoring.
OptionsThe class holding the processed options (exported as a value, not only a type). feedback and scoring receive it.
import { MatcherBaseClass } from '@zxcvbn-ts/core'
import type { Matcher, MatchExtended, MatchOptions } from '@zxcvbn-ts/core'

class MatchCompanyName extends MatcherBaseClass {
  match({ password }: MatchOptions): MatchExtended[] {
    // ...
    return []
  }
}

const companyNameMatcher: Matcher = {
  Matching: MatchCompanyName,
  feedback: (options, match) => ({ warning: 'Avoid the company name', suggestions: [] }),
  scoring: (match) => match.token.length,
}
Edit this page
Last Updated: 11/14/26, 7:35 PM
Contributors: MrWook
Prev
Framework examples
Next
Comparison