LVD-FluentUi-PasswordBox

A ReactJS password box built using the FluentUI library. It features a basic structure, with some additional features:

• a strength indicator which can be set to one of the three avaialble different flavours;
• a password status callout bubble, which shows the strength rules the password must meet and which have been met thus far.

Additionally, it exposes some of the customization options which are available for the standard FluentUI TextInput field.

Here's a static screenshot of how it all looks like using the default styling:

And also an animated gif which shows how it all respons to user input:

Contents

1. Installation
2. Demo
3. Basic Usage
4. Styling
5. Building
6. Customization Options
7. Computing password strength levels
8. Events
9. Changelog
10. Donate

Installation

npm install --save lvd-fluentui-passwordbox

Demo

The demo directory contains a compiled and ready-to-run example. Just open up the index.html file.

Basic Usage

import React from 'react';
import { PasswordBox, 
	StrengthIndicatorStyles } from 'lvd-fluentui-passwordbox';

class SomePasswordPage extends React.Component {
	constructor(props) {
		super(props);

		this._handlePasswordChanged =
			this._handlePasswordChanged.bind(this);
	}

	_handlePasswordChanged(oldValue, newValue) {
		// For instance, compute strength level or password rules
		//	See below for a built-in API to do that (though it's not mandatory)
	}

	render() {
		const strengthLevel = /* fetch or compute strength level from somehwere */;
		const strengthLevelText = /* fetch or compute strength level text from somehwere */;
		const rules = /* fetch or compute password rules from somewhere */;

		return (
			<PasswordBox 
				label="Your password, please"
				placeholder="Please fill in your new password"
				canReveal={true}
				required={true}
				underlined={true}
				emptyErrorMessage="The password is required, whether you like it or not!"
				passwordStrengthProps={{
					style: StrengthIndicatorStyles.intermittentBar,
					level: strengthLevel,
					text: strengthText
				}}
				passwordRulesProps={{
					rules: rules
				}}
				onPasswordChanged={this._handlePasswordChanged}
			/>
		);
	}
}

You can find a full working example here.

Styling

You can either directly include the dist/style.css into your html web page or use the @import directive inside your stylesheet if building using webpack:

@import '~lvd-fluentui-passwordbox/dist/style.css';

Also see the component itself.

Building

To build the demo application:

npm run build-app

To build the library:

npm run build-dist

To build both in one sitting:

npm run build

Customization Options

| What | Prop Name | Type | Notes | | --- | --- | --- | --- | | Label | label | string | Defaults to Password: | | Placeholder | placeholder | string | Defaults to Please fill in the password | | Descriptive text displayed below the field | description | string | Defaults to empty string. | | Allow user to reveal password | canReveal | boolean | Defaults to true | | Disable the field | disabled | boolean | Defaults to false | | Display field in underlined style. | underlined | boolean | Defaults to false | | Set field as required. | required | boolean | Defaults to false | | Set field as readonly. | readOnly | boolean | Defaults to false | | Message to display when field is required, but not filled in. | emptyErrorMessage | string | Defaults to You must fill in the password | | Password strength indication. | passwordStrengthProps | Password Strength Object | Defaults to not display password strength indication. See below. | | Password rules information. | passwordRulesProps | Password Rules Information Object | Defaults to not display any password rules information. See below. |

All the default values are defined here.

Password Strength Object

A plain javascript object with the following properties:

| Name | Type | Notes | | --- | --- | --- | | style | StrengthIndicatorStyles | Mandatory. See below info on the available values. | | level | PasswordStrengthLevels | Describes the currently assigned password strength level. Mandatory. See below info on the available values. | | percent | number | Optional. The percentage (values between 0 an 100) that describes the password strength. If not specified, defaults to the default percetnage assigned to the given password strength level. | | text | string | Optional. User-displayable text for the current password strength. If not specified, no text is displayed, with the exception of StrengthIndicatorStyles.textOnly, which displays the default text assigned to the given password strength level. |

Password Strength Levels

The following strength levels are available, fixed and may not be changed:

| Name | Usage | Notes | | --- | --- | --- | | Very Weak | PasswordStrengthLevels.veryWeak | By default, up to 20% strength. | | Weak | PasswordStrengthLevels.weak | By default, from 21% up to 40% strength. | | Medium | PasswordStrengthLevels.medium | By default, from 41% up to 60% strength. | | Strong | PasswordStrengthLevels.strong | By default, from 61% up to 80% strength. | | Very Strong | PasswordStrengthLevels.veryStrong | By default, from 81% up to 100% strength. |

Strength Indicator Styles

The following styles are available:

| Name | Usage | Notes | | --- | --- | --- | | Bar | StrengthIndicatorStyles.bar | Displays a contigous static bar filled in accordance with the determinted password strength percentage. Also displays an optional descriptive text, if given. Implemented here | | Intermittent Bar | StrengthIndicatorStyles.intermittentBar | Displays an intermittent static bar comprised of five segments, each segment corresponding to a strength level. The bar segments that are filled are determinted by the given password strength level. Also displays an optional descriptive text, if given. Implemented here | | Text Only | StrengthIndicatorStyles.textOnly | Just displays a descriptive text. Implemented here |

Password Rules Information Object

A plain javascript object with the following properties:

| Name | Type | Notes | | --- | --- | --- | | rules | Rule Evaluation Result Object[] | See below. | | container | Password Information Callout Container Properties Object | See below. | | title | Password Information Callout Title Properties Object | See below. | | icons | Password Information Callout Icons Properties Object | See below. |

Rule Evaluation Result Object

A plain javascript object with the following properties:

| Name | Type | Notes | | --- | --- | --- | | ruleMet | boolean | Whether or not the rule is satisfied or not. | | text | string | The descriptive text, displayed for the object. |

Password Information Callout Container Properties Object

These are the properties that are applied to the callout container itself. A plain javascript object with the following properties:

| Name | Type | Notes | | --- | --- | --- | | gapSpace | number | Defaults to 5. | | isBeakVisible | boolean | Defaults to true. | | beakWidth | number | Defaults to 15. | | directionalHint | DirectionalHint | Defaults to DirectionalHint.bottomCenter. | | style | object | Inline style applied. Defaults to { width: 300, padding: 10 }. | | calloutWidth | number | Defaults to 0. | | calloutMaxWidth | number | Defaults to 0. | | calloutMinWidth | number | Defaults to 0. |

These properties mirror their corresponding properties described for the FluentUI Callout component.

Password Information Callout Title Properties Object

These are the properties that are applied to the callout title. A plain javascript object with the following properties:

| Name | Type | Notes | | --- | --- | --- | | visible | boolean | Whether o not to show the tile. Defaults to true. | | text | string | The title text. Defaults to Password rules. | | variant | IFontStyles | Defaults to mediumPlus. | | style | object | Inline style applied. Defaults to { marginBottom: 0, fontWeight: FontWeights.semilight }. |

These properties mirror their corresponding properties described for the FluentUI Text component.

Password Information Callout Icons Properties Object

These properties describe various icons used for rendering the password rules. A plain javascript object with the following properties:

| Name | Type | Notes | | --- | --- | --- | | metIcon | Type | Icon name used when the rule is met. Defaults to CheckMark. | | notMetIcon | Type | Icon name used when the rule is not met. Defaults to Cancel. |

Please see the supported FluentUI icons.

Computing password strength levels

It is up to you how you compute the password strength level, just as long you provide one of the values described above.

However, for your convenience there's an API that you can use to do so:

• define your rules using by creating instances of:
  • PasswordCallbackRule;
  • PasswordLengthRule;
  • PasswordRegexRule.
• feed these rules to the built-in password evaluator.

Here's an example, similar to the one built-in the demo application:

import { PasswordEvaluator, 
	PasswordCallbackRule, 
	PasswordLengthRule } 
from 'lvd-fluentui-passwordbox';

function _hasLowercaseLetters(password) {
	return !!password.match(/[a-z]+/);
}

function _hasUppercaseLetters(password) {
	return !!password.match(/[A-Z]+/);
}

function _hasNumbers(password) {
	return !!password.match(/[0-9]+/);
}

function _hasNonAlphaNumericCharacters(password) {
	return !!password.match(/[^a-zA-Z0-9]+/);
}

function _getRules() {
	return [
		new PasswordLengthRule(8),
		new PasswordCallbackRule(_hasLowercaseLetters, 
			'Must contain lowercase letters'),
		new PasswordCallbackRule(_hasUppercaseLetters, 
			'Must contain uppercase letters'),
		new PasswordCallbackRule(_hasNumbers, 
			'Must contain numbers'),
		new PasswordCallbackRule(_hasNonAlphaNumericCharacters, 
			'Must contain non-alphanumeric characters')
	];
}

export function evaluatePassword(password) {
	const evaluator = new PasswordEvaluator(_getRules());
	return evaluator.evaluatePassword(password);
}

You may also create your own password rules objects, just as long as they provide:

• an evaluate(input) method, that returns true if the password satisfies the rule or false otherwise;
• a name property, that describes the rule - will be displayed to the user.

Events

| Event | Prop Name | Arguments | Notes | | --- | --- | --- | --- | | Value changed | onPasswordChanged | (oldPassword:string, newPassword:string) | Triggered whenever the value of the password field changes. | | Component initialized | onPasswordBoxInitialized | none | Triggered when the component is mounted by React. | | Component disposed | onPasswordBoxDisposed | (currentPassword:string) | Triggered when the component is un-mounted by React. | | Focused | onFocus | (event:React.FormEvent) | Triggered when the underlying password text field gains focus. | | Lost focus | onBlur | (event:React.FormEvent) | Triggered when the underlying password text field loses focus. |

Changelog

Version 0.0.5

• Updated type definitions.

Version 0.0.4

• Added type definitions.

Version 0.0.3

• A descriptive text can now be displayed below the text field input, using the description prop;
• Can now listen for the text field input focus event using the onFocus prop;
• Can now listen for the text field input blur event using the onBlur prop.

Donate

I put some of my free time into developing and maintaining this plugin. If helped you in your projects and you are happy with it, you can...