react-flexi-password-checklist :white_check_mark:

A flexible React component that validates user passwords against the custom password requirement checklist, in real-time.

It is so flexible that the only thing required for you to pass to the component is the password value itself, which is obvious for a password validator.
It gives you the ability to customize the rest of the things, which includes the password requirements to check, custom password requirement statements, title, and so on, as per your need.

So let's dive right in and see what this component has to offer.

Installing the package

npm install react-flexi-password-checklist

#### Usage
``javascript
import { FlexiPasswordChecklist } from 'react-flexi-password-checklist';
`
> Please note that it is a named export.

$3

react-flexi-password-checklist is carefully designed by keeping the end users at the center and to protect their privacy. It solely focuses on the end-user experience and aims at enhancing the same in the future.
The username and password data are only used to carry out the validations and are not sent to any servers of any kind or shared with anyone; nor does it encourage or support misuse of user data.

Table of Contents

- :ballot_box_with_check: Password Condition Checks
- minLength
- lengthMatch
- includesUsername
- matchPasswords
- specialChar
- upperCaseAndNumeric
- :u6307: Custom Condition Texts
- :a: Checklist Title
- :page_with_curl: Description Text
- :art: Custom Styles
- :abc: Custom Font
- :heavy_plus_sign: Custom Font Size
- :rainbow: Custom Font Color



First and foremost, you can choose what conditions/password requirements you want the password to be validated against.
You can customize the requirement checks based on your preference, by passing a _configuration object_ (config = { ...}) as a prop to the component.

You can pass the below _password validation conditions_ to the config object :

| Property name | Description | Type | Required | Allowed values | Default value |
| :---: | --- | :---: | :---: | :---: | :---: |
| minLength | Minimum character length that the password value should comprise of | integer | No | - | 8 |
| lengthMatch | Validates if the password value is equal to or more than the set minLength or default value | boolean | No | true/false | true |
| includesUsername | Checks whether password contains username value or not | boolean | No | true/false | false |
| matchPasswords | Checks whether the password and confirm password values match or not | boolean | No | true/false | false |
| specialChar | Checks whether the password contains allowed special characters or not | boolean | No | true/false | true |
| upperCaseAndNumeric | Checks if the password has at least one uppercase or numerical value | boolean/object | No | true/false | true |




> Below conditions are enabled, by default, even if you don't pass the config object :
> - lengthMatch (_minimum length set to 8_)
> - specialChar
> - upperCaseAndNumeric (_separate checks_)



Certain password validation conditions require you to pass the below values as props along with the config object and _password_ value :
- username
The username prop should consist of the form's _username_ value. It is a required value in case of includesUsername condition check.

- confirmPassword
The confirmPassword prop should consist of the form's _confirmPassword_ field value. It is a required value in case of matchPasswords condition check.

> Please be aware not to use prop names other than username, password, confirmPassword and config.



Let's say you want to enable the matchPasswords condition, where we check if the passwords in the _password_ and _confirm password_ field match.
We can get that to work as below :

#### For class components
`javascript
import React, { Component } from 'react';
import "./css/styles.css";
import { FlexiPasswordChecklist } from 'react-flexi-password-checklist';

class EnquiryForm extends Component {

constructor(props) {
super(props);

this.state = { username : "",
password : "",
confirmPassword : "" };
}

Rest of the code/>

confirmPassword={this.state.confirmPassword}
config={{ matchPasswords : true }}
/>

}
`

#### For function components
`javascript
import React, { Component } from 'react';
import "./css/styles.css";
import { FlexiPasswordChecklist } from 'react-flexi-password-checklist';

function EnquiryForm(props) {

const [ username, setUsername ] = useState("");
const [ password, setPassword ] = useState("");
const [ confirmPassword, setConfirmPassword ] = useState("");

Rest of the code/>

confirmPassword={confirmPassword}
config={{ matchPasswords : true }}
/>

}
`



As you can see above, we have passed confirmPassword as a prop along with password, after setting matchPasswords to true.
This is done as matchPasswords condition check relies on confirmPassword value for its validation.



Similar is the case with includesUsername condition.
We need to make sure that we pass username as a prop when includesUsername is set to true.

$3

You can use the below condition checks as a part of your custom password checklist :



- minLength
- lengthMatch
- includesUsername
- matchPasswords
- specialChar
- upperCaseAndNumeric



#### minLength

The minLength property takes an integer value which represents the minimum number of characters you want the user to enter for the check to get resolved.

#### Usage

`javascript
{ minLength : 12 }
`
#### Type
`css
integer
`
> _By default, the minLength property value is set to 8._



`javascript
config={ {minLength : 15} }
/>
`
In the above example, the lengthMatch condition would be enabled by default, with the minimum password character length set to 15.





#### lengthMatch

The lengthMatch password requirement checks if the password entered by the user matches the default or the desired character length set by you.

#### Usage
`javascript
{ lengthMatch : true/false }
`
#### Type
`css
boolean
`
> _By default, it is set to true._



You can skip adding it to the config object as it is enabled by default.
If you prefer using a custom minimum character length instead of the default value, for the lengthMatch check, you can simply add minLength property to the config object with its value set to the desired length.





#### includesUsername

The includesUsername password condition checks whether the entered password contains username or not. The condition check would not resolve to :white_check_mark: if the username, as a whole, is included in the entered password.
#### Usage
`javascript
{ includesUsername : true/false }
`
#### Type
`css
boolean
`
> _By default, it is set to false._



`javascript
password={this.state.password}
config={ {includesUsername : true} }
/>
`

If you plan to use this requirement/condition check, please make sure to pass username prop for the check to work as expected.





#### matchPasswords

The matchPasswords condition checks whether the passwords entered by the user in the _password_ and _confirm password_ field match or not.
#### Usage
`javascript
{ matchPasswords : true/false }
`
#### Type
`css
boolean
`
> _By default, it is set to false._



`javascript
confirmPassword={this.state.confirmPassword}
config={ {matchPasswords : true} }
/>
`

In order to use this condition check, please make sure to pass confirmPassword prop for the validation to work as expected.





#### specialChar

The specialChar requirement checks whether the user entered password contains special characters or not.
#### Usage
`javascript
{ specialChar : true/false }
`
#### Type
`css
boolean
`
> _By default, it is set to true._

The condition would check for the following special characters in the password value - !@#*_|.?



You could see that the specialChar condition's default text has a keyword - allowed, with blue font color.







A simple mouse hover or a tap action on the allowed keyword would reveal the allowed special characters that the condition would check for, in the password value.









#### upperCaseAndNumeric

The upperCaseAndNumeric requirement checks if the entered password includes at least one number or an uppercase letter, or both.

#### Usage
`javascript
{ upperCaseAndNumeric : true/false }
`
#### Type
`css
boolean
`
> _By default, it is set to true._



When you set upperCaseAndNumeric value to either true or false, both the condition checks i.e. upperCase as well as numeric would be enabled/disabled.
To have more control, you can assign upperCaseAndNumeric property to an object rather than a plain boolean value.
The object would allow further splitting of the conditions into either just upperCase condition check or a numeric one.
#### Usage
`javascript
{ upperCaseAndNumeric : { upperCase : true/false, numeric : true/false } }
`
#### Type
`css
object
`



Let's say you don't want the upperCase condition as a part of your password requirement.
`javascript
password={this.state.password}
confirmPassword={this.state.confirmPassword}
config={ {
matchPasswords : true,
includesUsername : true,
upperCaseAndNumeric : { numeric : true }
} }
/>
`
As demonstrated above, we have set upperCaseAndNumeric value to { numeric : true }, therefore, eliminating the upperCase check from the group.


> Setting upperCaseAndNumeric value to an empty object will remove both the checks. It is recommended to rather set the value to false if you don't plan to add upperCase and numeric checks.

Thus, the object assignment would allow you to be more specific with the condition enable/disable part rather than treating both the checks as a single unit.

$3

You can frame the password requirement texts in your own verbiage instead of the default ones.
Enable it by passing the conditionTexts property to the config object.

#### Usage

`javascript
{ conditionTexts : {
lengthMatchText : "",
includesUsernameText : "",
matchPasswordsText : "",
specialCharText : "",
upperCaseAndNumericText : { upperCaseText : "" ,
numericText : ""
}
}
}
`
#### Type

`css
object
`
> _It is not enabled by default._
> It is not mandatory to include each and every condition text in the conditionTexts object.



For example, let's say you don't wish to customize condition texts for matchPasswords and specialChar.
In this case, you can simply eliminate it from the conditionTexts object, like below :
`javascript
password={this.state.password}
confirmPassword={this.state.confirmPassword}
config={ {
minLength : 10,
conditionTexts : {
lengthMatchText : "Minimum length should be 10",
includesUsernameText : "Avoid using username in your password",
upperCaseAndNumericText : { upperCaseText : "Please use at least one uppercase character",
numericText : "Please include at least one number"
}
},
matchPasswords : true,
includesUsername : true
} }
/>
`



This would set the default condition texts for matchPasswords and specialChar, while texts for the rest of the conditions would be the ones that are included in the conditionTexts object.





If you wish to frame all of them as per your text content, you can include them all in the conditionTexts object.

`javascript
password={this.state.password}
confirmPassword={this.state.confirmPassword}
config={ {
minLength : 10,
conditionTexts : {
lengthMatchText : "Minimum length should be 10",
includesUsernameText : "Avoid using username in your password",
matchPasswordsText : "Both password fields must match",
specialCharText : "Please use at least one of the following special characters - !@#*_|.?",
upperCaseAndNumericText : { upperCaseText : "Please use at least one uppercase character",
numericText : "Please include at least one number"
}
},
matchPasswords : true,
includesUsername : true
} }
/>
`


> Please note that if you have the lengthMatch condition enabled and plan to set a custom condition text for the same, kindly make sure to mention the minimum character length value in the lengthMatchText text content.
> It should be in sync with the minLength property value passed by you in the config object.
>
> For example, if the passed minLength property value is 10, please mention that the minimum character length value is 10 in the lengthMatchText text content.
`javascript
config={ { minLength : 10,
conditionTexts : { lengthMatchText : "Please make sure your password has at least 10 characters." }
} }
`




>
> In case you have not added minLength to the config object, please mention the minimum character length value as 8 in the lengthMatchText text content.
`javascript
config={ { conditionTexts : { lengthMatchText : "Please make sure your password has at least 8 characters." } } }
`




> Doing so would help to avoid confusion for the end user.
> The minimum character length value in the lengthMatch condition's default text stays in sync with the passed minLength property value.



So that's how you can have your own custom condition texts.

$3

You can set your own checklist title, keep the default one, or have no title at all.

#### Usage

`javascript
{ title : true/false }
`
#### Type

`css
boolean
`
> _By default, it is set to false._



Let's understand it better through examples.

All we need to do is set the title property to true, in our good old config object.
Doing so will set the title text in the checklist window to the default value - Password checklist.

`javascript
password={this.state.password}
confirmPassword={this.state.confirmPassword}
config={ { title : true,
matchPasswords : true,
includesUsername : true
} }
/>
`


To set a custom title, you need to assign an object to the title property.
#### Usage

`javascript
{ title : { text : "" } }
`
#### Type

`css
object
`



Let's have a closer look at it.

`javascript
password={this.state.password}
confirmPassword={this.state.confirmPassword}
config={ { title : { text : "Password Validator" / custom text for the title property / },
matchPasswords : true,
includesUsername : true
} }
/>
`

The title object must have a property named - text.
The text property only accepts a string value, which holds your custom checklist title.
> If you pass a value other than a string or even an empty string, to the text property, the default title text would be displayed.



`javascript
{ text : "Password Validator" }
`


> Please note that it expects the object with text as the property name. If you use a different property name, the title text displayed would be the default one - Password checklist.

The below code will not set the title text to My Password Validator.
`javascript
    config={ { title : { customText : "My Password Validator" } } }
/>
`

$3

Description Text allows you to add extra textual content. It could be a place for you to explain the password requirement instructions in more detail or maybe a brief information about how you are securely handling user passwords.

#### Usage

`javascript
{ description : true/false }
`
#### Type

`css
boolean
`
> _By default, it is set to false._



To set a custom description text, you need to assign an object to the description property.
#### Usage

`javascript
{ description : { text : "" } }
`
#### Type

`css
object
`

`javascript
password={this.state.password}
confirmPassword={this.state.confirmPassword}
config={ {
matchPasswords : true,
includesUsername : true,
title : true,
description : { text : "Please make sure that your password meets all the requirements listed below..." }
} }
/>
`


The assigned object should have a property name as text.
The text property only accepts a string value, which holds your description text.
> If you pass a value other than a string or even an empty string, to the text property, the default description text would be displayed.
`javascript
{ text : "Please make sure that your password meets all the requirements listed below..." }
`



> Please note that it expects the object with text as the property name. If you use a different property name, the description text displayed would be the default one - _To keep your valuable information safe, we require that you use a strong password that meets the minimum requirements listed below_.

$3

Custom Styles enable all-new personalization features for description text, checklist title and password conditions, making the customization experience even more seamless.
It provides you the flexibility to individually target textual content and customize its font face, size, and color, making it easy for the components to adapt to the custom styles of your choice, as font faces/styles are generally subjective.

#### Usage

`javascript
{
styles = {
title : { fontFace : "", fontSize : , fontColor : "" },
description : { fontFace : "", fontSize : , fontColor : "" },
conditions : { fontFace : "", fontSize : , fontColor : "" }
}
}
`
#### Type

`css
object
`
> _It is not enabled by default._



You can see that the styles property follows a simple nested object design.



It consists of three properties - _title_, _description_ and _conditions_.
As the property names indicate, _title_ will hold styling data for the checklist title, _description_ would consist of styles for description text and finally, _conditions_ will enable customization capabilities for the condition texts.

> All the three properties - _title_, _description_ and _conditions_ accept styling properties in the form of an object.



To enable Custom Styles, you just need to add the styles property to the config object. The styles property itself is an object that holds all the style elements and style components.





#### What are _style elements_ and _style components_?



In this case, style elements are the various styling properties that you would use here, such as _fontFace_, _fontSize_ and _fontColor_.
Whereas style components are the components we discussed above, upon which the style element properties will be applied - _title_, _description_ and _conditions_.



We will be hearing the terms - style elements and style components a lot, later down the lane.
> It is not mandatory to include each and every style element (_fontFace, fontSize, fontColor_) or style component (_title, description, conditions_) in the styles object.



Before we get to all the amazing examples, let's go through some important aspects about Custom Styles.
> If you don't pass the styles property to the config object, the default styling properties will be applied for the style components.
>
> The order of the style elements or style components doesn't matter.
>
> If you have passed the styles property to the config object with custom fontFace and fontSize, let's say, for just the _title_ and _description_ component, the respective changes would be applied for _title_ and _description_ only, while styling for the rest of the style components would be the default one.



Let's explore the style elements in more detail.
As mentioned above, you can customize below style elements :
- Font Face
- Font Size
- Font Color

$3

You have the freedom to choose your own font, instead of the default one, for the checklist title, description text and password condition texts.
We are talking about two types of fonts here -
- Pre-installed/system fonts
- Fonts imported in the .css file using the @font-face rule

#### Usage

`javascript
{ styles = {