Password UI Component

Overview

Your Buyer customers need to be onboarded and authenticated on the Weavr platform. You can find more information on how to onboard your Buyer customers here.

One way to authenticate a user is by collecting their password - you must do this in a way so that your application does not have access to the plain text version of such password.

Embed the password UI component

The Password UI component lets you collect your customer’s password securely and converts it into a token, which you can safely send to Weavr using the API.

tip

To use Weavr UI components, you must first set up the Weavr UI library in your application.

password(name, options, formId);

Parameter	Type	Required?	Description
`name`	string	Required	A unique name that describes the component.
`options`	object	Optional	Describes the styling capabilities that are available on the component in subject.
`formId`	string	Optional	The form id the password component is in if any.

const passwordComponent = weavrComponents.capture.password(
  name,
  options,
  formId
);

Mounting

To display the component on the screen, it's necessary to mount it to the DOM. This involves creating a wrapping element that will serve as the container for injecting the secure frame. Be sure to assign an id to the HTML element.

<!--login.html-->
<div id="password-example"></div>

// secure-password.js
const passwordComponent = weavrComponents.capture.password(
  name,
  options,
  formId
);
passwordComponent.mount("#password-example");

Look and feel

Look and feel can be set according to the state of the UI Component. The following are the states:

base - the default state for all components
empty - component will transition to this state whenever the input is cleared
valid - component will transition to this state whenever the user input is valid
invalid - component will transition to this state whenever the user input is invalid

You can specify your custom styles via the options parameter when initialising the component:

const passwordComponent = weavrComponents.capture.password(
  name,
  {
    // Definition found below
  },
  formId
);

Parameter Definitions

style The specified properties will be applied on the component when it is mounted.

Property	Type	Required?	Description
`classNames`	object	Optional	Defines which classes are to be appended to the wrapping element depending on the state.
`placeholder`	string	Optional	Placeholder text to be shown in the input field.
`maxlength`	number	Optional	The allowed maximum length of the input field
`autocorrect`	string	Optional	Defines should the field be autocorrected.
`disabled`	boolean	Optional	Transitions the component to a disabled state if true
`style`	object	Optional	Defines the styles that the component will have for each state.
`validationMode`	string	Optional	When should the state change. `onTouch` or `onBlur`
`strengthCheck`	boolean/object	Optional	Defines if the component should be loaded with strength check UI.

const passwordComponent = weavrComponents.capture.password(
    'secure-password-1',
    {
        placeholder: 'Password',
        style: {
            base: {
                fontSize: '1rem',
                fontFamily: 'Fuggles',
                backgroundColor: '#fff',
                ...
            },
            ...
        },
        classNames: {
            base: 'example-class base-class',
            disabled: 'disabled-class',
            ...
        },
        disabled: false,
        validationMode: 'onBlur',
        ...
    }
)

Property Definitions

`classNames`

To enhance the flexibility of customizing the appearance of the component's wrapping element, you have the option to input CSS class names into the classNames property, which is accessible in all components. Please ensure that the CSS classes you pass to the component's className property are declared in the root DOM for them to take effect. For additional details on the classNames property, kindly refer to the respective component's documentation.

Property	Type	Required?	Description
`base`	string	Optional	Defines the default classes to be appended to the wrapping element.
`empty`	string	Optional	Defines the classes to be appended to the wrapping element when field is empty.
`focus`	string	Optional	Defines the classes to be appended to the wrapping element when field is focused.
`valid`	string	Optional	Defines the classes to be appended to the wrapping element when field is valid.
`invalid`	string	Optional	Defines the classes to be appended to the wrapping element when field is invalid.
`autofill`	string	Optional	Defines the classes to be appended to the wrapping element when field is autofilled.
`disabled`	string	Optional	Defines the classes to be appended to the wrapping element when field is disabled.
`active`	string	Optional	Defines the classes to be appended to the wrapping element when field is active.

const passwordComponent = weavrComponents.capture.password(
    'secure-password-1',
    {
        classNames: {
            base: 'example-class base-class',
            ...,
            disabled: 'disabled-class',
        },
    }
)

`style`

Upon mounting, the component adopts the defined styles and adjusts its appearance based on its current state. This object encompasses the following properties.

Property	Type	Required?	Description
`base`	object	Optional	Defines the default style appearance.
`empty`	object	Optional	Defines the style appearance when component is in an empty state.
`valid`	object	Optional	Defines the style appearance when component is in a valid state.
`invalid`	object	Optional	Defines the style appearance when component is in an invalid state.

Each property follows the object format outlined below. This object features the following parameters, with each one accepting inputs based on the provided link.

note

The Pseudo-Class Object is a recursive structure composed of the same properties listed below. During recursion, the properties specific to the Pseudo-Class are omitted.

Parameter	Type	Required	Description
`backgroundColor`	string	Optional	Background color
`border`	string	Optional	Border width, style, and color
`borderRadius`	string	Optional	Border rounded corners
`classesNames`	string	Optional	Custom styling, or referencing in your stylesheet
`color`	string	Optional	Text color
`fontFamily`	string	Optional	Text font
`fontSize`	string	Optional	Font size
`fontSmoothing`	string	Optional	Font smoothing (anti-aliasing)
`fontStyle`	string	Optional	Text Style (italic or normal)
`fontVariant`	string	Optional	Text with small caps (or other font variants)
`fontWeight`	string	Optional	Text weight (thickness or boldness)
`height`	string	Optional	Component height
`letterSpacing`	string	Optional	Space between characters in the text
`lineHeight`	string	Optional	Height of text
`margin`	string	Optional	Spacing within component
`padding`	string	Optional	Spacing inside Component (between content & border)
`textAlign`	string	Optional	Horizontal text alignment
`textDecoration`	string	Optional	Text underline or overline
`textIndent`	string	Optional	First line text indentation
`textShadow`	string	Optional	Text shadow effect
`textTransform`	string	Optional	Text capitalization

`:webkit-autofill`	object*	Optional	Pseudo-Class Used to style an `<input>` element has its value autofilled by the browser
`::placeholder`	object*	Optional	Pseudo-Class Used to style the placeholder text input or text area element
`::selection`	object*	Optional	Pseudo-Class Used to style text that has been highlighted by the user
`:active`	object*	Optional	Pseudo-Class Applicable to input type components.Components will transition to this state whenever the user input is available
`:disabled`	object*	Optional	Pseudo-Class Applicable to the input type components. Components will transition to this state whenever the user input is disabled
`:focus`	object*	Optional	Pseudo-Class Triggered when a user selects an element via click, tap or “Tab” key
`:hover`	object*	Optional	Pseudo-Class Triggered when a user interacts with an element using a pointed device e.g. cursor

const passwordComponent = weavrComponents.capture.password(
    'secure-password-1',
    {
        style: {
            base: {
                fontSize: '1rem',
                fontFamily: 'Fuggles',
                backgroundColor: '#fff',
                border: '1px solid white',
                ':hover': {
                    backgroundColor: '#fefefe',
                    border: '1px solid grey',
                },
                '::placeholder': {
                    fontSize: '12px',
                    fontFamily: 'Inter'
                },
                ...
            },
            valid: {
                fontSize: '1rem',
                fontFamily: 'Fuggles',
                backgroundColor: '#fff',
                border: '1px solid green',
                ...
            },
            ...
        }
    }
)

`strengthCheck`

The property can accept either a boolean value or an object. If you provide only a boolean, the component will display the default password strength UI included in the component library. If you wish to customize the appearance of the strength checker, you'll need to define the style based on the properties listed below.

Parameter	Type	Required	Description
`backgroundColor`	string	Optional	Background color of the strength checker.
`border`	string	Optional	Border width, style, and color.
`borderRadius`	string	Optional	Border rounded corners.
`classNames`	string	Optional	Appends the class names to the element and inherits css from the defined class names.
`hideText`	string	Optional	Hide or show text.
`weakColor`	string	Optional	Color of strength checker when password is weak.
`mediumColor`	string	Optional	Color of strength checker when password is of medium strength.
`strongColor`	string	Optional	Color of strength checker when password is strong.

const passwordComponent = weavrComponents.capture.password(
  "secure-password-1",
  {
    // strengthCheck: true, // Shows strength checker with default styling
    strengthCheck: {
      // optional (defaults to false) - all object values are also optional
      borderRadius: "2px",
      border: "1px solid black",
      backgroundColor: "white",
      weakColor: "red",
      mediumColor: "orange",
      strongColor: "green",
      // hideText: true
    },
  }
);

API functions

You can interact with the library's components by utilizing the exposed functions. The below is a list of functions exposed for the Password component.

`mount`

The mount function is called in order to mount a component into the defined selector.

password.mount(selector);

`unmount`

The unmount function is called in order to unmount a component from its selector.

note

Once a component is unmounted it can be remounted. One can remount the component utilizing the mount function.

password.unmount();

`destroy`

The destroy function can be used to remove the element and its references from the DOM.

note

Once a component is destroyed it cannot be remounted. The component will be removed from Document Object Model (DOM) alongside any references and will need to be re-initialised.

password.destroy();

`on`

This function makes event listeners available for interacting with the component during events.

password.on(event, listener);

`off`

This function provides the capability to detach event listeners from the component.

password.off(event, listener);

`focus`

This function provides the capability to focus within the component.

password.focus();

`blur`

This function provides the capability to blur out of the component.

password.blur();

`clear`

This function provides the capability to clear the password field.

password.clear();

`createToken`

This function provides the capability to tokenise the input value. A promise is returned and the resolved value is the tokenised value.

form.createToken();

Events

The Password component will trigger the following events. You can listen to these events by attaching event listeners.

Event	Trigger condition
`ready`	On component successfully initialisation.
`change`	When component's state changes.
`error`	An error in the API will fire this.
`focus`	Triggered when input element is in focus.
`blur`	When input element loses focus
`keyup`	Triggered on key up, providing a key parameter representing the key that triggered the event. The keys triggering the event are either 'Enter' or 'Escape'.
`submit`	On 'Enter' key up, or other submission buttons.
`redirectfocus`	Called when focus is leaving the current input element, to the next/previous element. Fires with an event specifying if the focusDirection is previous or next.
`autofill`	When input has been autofilled.
`autofill-cleared`	When autofilled content has been cleared.
`strength`	Triggered with every strength state change.

Capabilities

1. Showing password strength

It is useful to give an indication to the user on the expected strength of an entered password when you are onboarding a new buyer or when they are changing their password. When creating/changing a password component, you can

Enable the strengthCheck capability in the Password UI Component
Listen for the strength event triggered by the Password UI Component

This is an example of how to enable the strengthCheck capability:

const passwordComponent = weavrComponents.capture.password(
  "secure-password-1",
  {
    placeholder: "Password",
    maxlength: 20,
    // strengthCheck: true, // Shows strength checker with default styling
    strengthCheck: {
      // optional (defaults to false) - all object values are also optional
      borderRadius: "2px",
      border: "1px solid black",
      backgroundColor: "white",
      weakColor: "red",
      mediumColor: "orange",
      strongColor: "green",
      // hideText: true
    },
  }
);

Listening and capturing a strength event, note that there are 4 possible states:

Very Weak: { id: 0, value: 'Very Weak' }
Weak: { id: 1, value: 'Weak' }
Medium: { id: 2, value: 'Medium' }
Strong: { id: 3, value: 'Strong' }

passwordComponent.on("strength", (e) => {
  // Strength of password has changed
  console.log("Password strength:", e.value);
});

Examples

For more examples related to matching passwords and changing passwords, please consult the provided documentation.

1. Input tokenisation

To convert the entered value in the password component, you must initialize and mount the component successfully. Subsequently, you need to invoke the createToken() function, which will yield a tokenised value. This value can then be utilized in the authentication flow within your application.

<!-- Define a form in which you will ask your customer to input their password -->
<form onSubmit="onSubmit(); return false;">
  <!-- Normal input to accept the username-->
  Username: <input type="input" name="user" />
  <!-- Div to be injected with the password component -->
  Password:
  <div id="password"></div>

  <input type="submit" value="Login" />
</form>

<script lang="js">
  const passwordComponent = weavrComponents.capture.password(
          'secure-password-1',
          {
              placeholder: 'Password',
              maxlength: 20,
              ...
          }
  )

  passwordComponent.mount('#password')

  function onSubmit() {
      passwordComponent.createToken()
              .then(res => {
                  // Successfully created token
                  console.log(res)

                  // Outputs:
                  // {
                  //   "tokens": {
                  //     "{{ component name }}": "{{ token }}"
                  //   }
                  // }
              })
              .catch(e => {
                  // Error while creating the token
              })
  }
</script>

Overview​

Embed the password UI component​

Mounting​

Look and feel​

Parameter Definitions​

Property Definitions​

classNames​

style​

strengthCheck​

API functions​

mount​

unmount​

destroy​

on​

off​

focus​

blur​

clear​

createToken​

Events​

Capabilities​

1. Showing password strength​

Examples​

1. Input tokenisation​

Overview

Embed the password UI component

Mounting

Look and feel

Parameter Definitions

Property Definitions

`classNames`

`style`

`strengthCheck`

API functions

`mount`

`unmount`

`destroy`

`on`

`off`

`focus`

`blur`

`clear`

`createToken`

Events

Capabilities

1. Showing password strength

Examples

1. Input tokenisation