README.md

Password Input

View on MongoDB.design

Installation

Yarn

yarn add @leafygreen-ui/password-input

NPM

npm install @leafygreen-ui/password-input

Example

import { PasswordInput } from '@leafygreen-ui/password-input';

// Multiple notifications
<PasswordInput
  label="New password"
  stateNotifications={[
    {
      notification: "i'm an error",
      state: 'error',
    },
    {
      notification: "i'm a warning",
      state: 'warning',
    },
    {
      notification: "i'm valid",
      state: 'valid',
    },
    {
      notification: "i'm waiting",
      state: 'none',
    },
  ]}
  autoComplete="new-password"
  id="new-password"
  onChange={() => console.log('onChange callback')}
/>;

// Single notification
<PasswordInput
  label="Confirm Password"
  stateNotifications={[
    {
      notification: "i'm an error",
      state: 'error',
    },
  ]}
  autoComplete="new-password"
  id="new-password"
/>

// Custom notification
<div>
  <PasswordInput
    label="Password"
    stateNotifications="error"
    aria-describedby="custom-error-id"
    autoComplete="current-password"
    id="current-password"
  />
  <Banner id="custom-error-id" variant="danger" />
</div>

// General notification
<PasswordInput
  label="Password"
  stateNotifications="error"
  autoComplete="current-password"
  id="current-password"
/>

<PasswordInput
  label="Password"
  stateNotifications="valid"
  autoComplete="current-password"
  id="current-password"
/>

Properties

Prop	Type	Description	Default
id	string	id associated with the password input.
label	string	Text shown above the password input.
value	string	The controlled value of the password input.
disabled	boolean	Disables the password input but still allows you to toggle password visibility.	false
onChange	function	The event handler function for the 'onchange' event. Accepts the change event object as its argument and returns nothing.
onBlur	function	The event handler function for the 'onblur' event. Accepts the focus event object as its argument and returns nothing.
placeholder	string	The placeholder text shown in the input field before the user begins typing.
autoComplete	string	Specifies what permission the user agent has to provide automated assistance in filling out form field values, as well as guidance to the browser as to the type of information expected in the field. More info can be found here.	new-password
size	'small' | 'default' | 'large'	Determines the size of the input.	default
errorMessage	string	Error message that appears below the input. Renders only if aria-disabledby=undefined and (stateNotifications='error' or stateNotifications='warning')	'This input needs your attention'
successMessage	string	Success message that appears below the input. Renders only if aria-disabledby=undefined and stateNotifications='valid'	'Success'
stateNotifications	Array<{notification: string; state: 'error' | 'warning' | 'valid' | 'none'}> or 'error' | 'warning' | 'valid' | 'none'	Determines what notifications will appear below the password input. The array determines the overall input state. If at least one object has 'error' | 'warning' as the state value, the input will display a red outline. If all objects have valid as the state value, then the input will display a green outline. If none of the conditions above are met, then the input will display a default state. To use a custom error notification container rather than the default provided in this component, stateNotifications will only require a string with the appropriate state value. In addition, the aria-describedby attribute must be provided with the id of the custom notification container. You can read more about aria-describedby here.	[]
className	string	The className passed to the root element of the component.
...	native input attributes	Any other props will be spread on the root input element

States

const State = {
  Error: 'error', // red x icon, red text
  Warning: 'warning', // red warning icon, red text
  Valid: 'valid', // green checkmark, black text
  None: 'none', // gray checkmark, gray text
} as const;

Validation Feedback

Password input has 3 different supported options for validation feedback:

1. Pass the id of a custom notification as the aria-describedby prop and pass a state value string as the stateNotifications prop to link a custom notification to the password input.
2. Pass an array of notifications as the stateNotifications prop for cases where multiple notifications may need to render. aria-describedby prop must be undefined in this case.
3. Pass a state value string and pass a string to the errorMessage prop or successMessage prop for cases where only a single notification will ever render. aria-describedby prop must be undefined and stateNotifications prop must be a string in this case.

Special Case

Aria Labels

Either label or aria-labelledby or aria-label must be provided a string, or there will be a console error. This is to ensure that screenreaders have a description for what the PAssword Input does.

Aria Describedby

To use a custom error notification container rather than the state notifications array or default error or success message provided in this component, stateNotifications requires a string with the appropriate state value. In addition, the aria-describedby attribute must be provided with the id of the custom notification container. You can read more about aria-describedby here.