ChangePassword

ChangePassword component enables end users to change their password.

Props

Name	Description	Type
onSuccess?	Callback function triggered when password is successfully updated	`() => void`
onError?	Callback function triggered when change password fails	`(error: Error) => void`
validators?	Custom password validations	`ValidatorOptions[]`
components?	Submit button	`ChangePasswordComponents`
displayText?	Text to override in the component	`ChangePasswordDisplayText`

Basic Usage

ChangePassword has onSuccess handler that will be called after successful password change. You may use this callback to run any custom handling, such as navigating route or rendering confirmation messages.

import React from 'react';
import { AccountSettings } from '@aws-amplify/ui-react';

function App() {
  const handleSuccess = () => {
    alert('password is successfully changed!')
  }
  
  return (
    <AccountSettings.ChangePassword onSuccess={handleSuccess}/>
  );
}

Custom Validation

You can override the default password validator with your own custom validator. To do so, you can use the validators prop, which takes an array of ValidatorOptions:

interface ValidatorOptions {
  validationMode: 'onBlur' | 'onChange' | 'onTouched';
  validator: (value: string) => boolean;
  message: string;
}

onBlur validates password on every blur event
onChange validates password on every change event
onTouched validates password on first blur, and on every change event after the first blur.

For example, following is a minLength validator that validates on every change:

const minLength = {
  validationMode: 'onChange',
  validator: (password) => password.length >= 4,
  message: 'Password must have length 4 or greater',
};

You can pass multiple validators to ChangePassword to override the default validator:

import React from 'react';
import { AccountSettings } from '@aws-amplify/ui-react';

function App() {
  const minLength = {
    validationMode: 'onChange',
    validator: (password) => password.length >= 4,
    message: 'Password must have length 4 or greater',
  };

  const maxLength = {
    validationMode: 'onChange',
    validator: (password) => password.length <= 12,
    message: 'Password must have length 12 or less',
  };
  
  const handleSuccess = () => {
    alert('password is successfully changed!')
  }
  
  return (
    <AccountSettings.ChangePassword 
      onSuccess={handleSuccess} 
      validators={[minLength, maxLength]}
    />
  );
}

Component Overrides

You can provide your own UI components to override parts of ChangePassword. It supports the following slots:

Name	Description	Type
CurrentPasswordField?	Password field for current password	`PasswordFieldProps`
NewPasswordField?	Password field for new password	`PasswordFieldProps`
ConfirmPasswordField?	Password field for confirm password	`PasswordFieldProps`
ErrorMessage?	Error alert that displays on change password errors	`ErrorMessageComponentProps`
SubmitButton?	Submit button	`SubmitButtonProps`

Reusing default components

Default components are accessible through AccountSettings.ChangePassword.COMPONENT_NAME (e.g. AccountSettings.ChangePassword.NewPasswordField) for your convenience. This is useful if you're interested in modifying just a small part of UI instead of overriding the whole component.

function App() {
  const components = {
    NewPasswordField: (props) => (
      <AccountSettings.ChangePassword.NewPasswordField
        {...props} 
        label="Custom New Password Label" 
      />
    ),
  }

  return (
    <AccountSettings.ChangePassword components={components} />
  );
}

Note that spreading props is necessary so that event listeners like onChange or html attributes like name are passed correctly. If you're providing your own custom components, make sure required props are passed onto your elements.

Props and Examples

Here are the required props and examples for overriding each slot.

PasswordFields

ChangePassword has three password fields that you can override: CurrentPasswordField, NewPasswordField, and ConfirmPasswordField. They all take the same props:

Name	Description	Type
onBlur	Blur handler for the input. This must be passed to your input element.	`React.FocusEventHandler<HTMLInputElement>`
onChange	Change handler for the input. This must be passed to your input element.	`React.ChangeEventHandler<HTMLInputElement>`
name	HTML name for the input. This must be passed to your input element.	`React.ChangeEventHandler<HTMLInputElement>`
fieldValidationErrors?	List of validation errors for the password field.	`string[]`

You can reuse the AccountSettings.ChangePassword.<COMPONENT_NAME>:

function App() {
  const components = {
    NewPasswordField: (props) => (
      <AccountSettings.ChangePassword.NewPasswordField
        {...props} 
        label="Custom New Password Label" 
      />
    ),
    ConfirmPasswordField: (props) => (
      <AccountSettings.ChangePassword.ConfirmPasswordField
        {...props} 
        label="Custom Confirm Password Label" 
      />
    ),
  }

  return (
    <AccountSettings.ChangePassword components={components} />
  );
}

The following example overrides the CurrentPasswordField with native html:

function App() {
  const components = {
    CurrentPasswordField: ({ 
      fieldValidationErrors,
      name,
      onBlur,
      onChange
    }) => (
      <>
        <input name={name} onBlur={onBlur} onChange={onChange} type="password" />
        {fieldValidationErrors?.map((error) => (
          <p key={error} role="alert">{error}</p>
        ))}
      </>
    )
  };
}

ErrorMessage

Props:

Name	Description	Type
children?	Contains error message string	`string`

The following example overrides the error message component with Heading and Text primitives.

import { Heading, Text } from '@aws-amplify/ui-react';

function App() {
  const components = {
    ErrorMessage: ({ children }) => (
      <>
        <Heading>Custom Error Message</Heading>
        <Text variation="warning">{children}</Text>
      </>
    )
  };
  
  return (
    <AccountSettings.ChangePassword components={components} />
  );
}

SubmitButton

Props:

Name	Description	Type
isDisabled	Boolean representing whether account deletion is in progress. Your delete button should be disabled if this is set to true.	`boolean`

You can reuse the AccountSettings.ChangePassword.SubmitButton:

import { AccountSettings } from '@aws-amplify/ui-react';

const components  = {
  SubmitButton: (props) => (
    <AccountSettings.ChangePassword.SubmitButton {...props}>
      My Custom Button
    </AccountSettings.ChangePassword.SubmitButton>
  )
}

or use button primitive directly:

import { AccountSettings, Button } from '@aws-amplify/ui-react';

const components  = {
  SubmitButton: (props) => <Button {...props}>My Custom Button</Button>
}

The following example replaces SubmitButton with native html button:

function App() {
  const components = {
    SubmitButton: ({ onClick, isDisabled }) => (
      <button type="submit" onClick={onClick} disabled={isDisabled}>
        Custom Button Text
      </button>
    )
  };
  
  return (
    <AccountSettings.ChangePassword components={components} />
  );
}

Text and labels

All text in the ChangePassword component is customizable with the displayText prop.

import { AccountSettings } from '@aws-amplify/ui-react';

function App() {
  return (
    <AccountSettings.ChangePassword 
      displayText={{
        currentPasswordLabel: 'Enter current password',
        newPasswordLabel: 'Enter new password',
        confirmPasswordLabel: 'Confirm your password',
        updatePasswordText: 'Update your password',
      }}  
    />
  );
}

Theming

ChangePassword component is built upon our robust Amplify UI theming system. To get started, add a theme object and set the appropriate design tokens. You can then pass that theme to the ThemeProvider so the changes can take affect.

import { AccountSettings, Card, ThemeProvider } from '@aws-amplify/ui-react';

const theme = {
  name: 'custom-theme',
  tokens: {
    colors: {
      border: {
        primary: { value: '{colors.neutral.40}' },
        secondary: { value: '{colors.neutral.20}' },
        tertiary: { value: '{colors.neutral.10}' },
      },
    },
    radii: {
      small: { value: '2px' },
      medium: { value: '3px' },
      large: { value: '4px' },
      xl: { value: '6px' },
    },
  },
};

function App() {
  return (
    <ThemeProvider theme={theme}>
      <Card width="800px">
        <AccountSettings.ChangePassword />
      </Card>
    </ThemeProvider>
  );
}