PasswordField

PasswordField allows users to input passwords with the convenience of full password manager support.

Demo

Usage

Import the PasswordField component and provide a label for accessibility/usability.

Password

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

export const DefaultPasswordFieldExample = () => {
  return <PasswordField label="Password" />;
};

Hiding the show password button

Use the hideShowPassword prop to hide the show password button.

Password

import * as React from 'react';
import { PasswordField, Button, Flex } from '@aws-amplify/ui-react';

export const HidePasswordFieldExample = () => {
  const [hideShowPassword, setHideShowPassword] = React.useState(true);
  const toggleHide = () => {
    setHideShowPassword(!hideShowPassword);
  };
  return (
    <Flex direction="column">
      <PasswordField
        label="Password"
        name="password"
        hideShowPassword={hideShowPassword}
      />
      <Button onClick={toggleHide}>
        HideShowPassword: {hideShowPassword.toString()}
      </Button>
    </Flex>
  );
};

Autocomplete - supporting password managers

Use the autoComplete prop to tell browser how to populate a password field. Options for autoComplete are current-password (default) and new-password.

If customers are logging in, setting autoComplete is not required because current-password is the default. If customers are signing up for a new account, set autoComplete to new-password.

See MDN for more information on autocomplete.

Signup form example: new-password

import {
  Flex,
  Heading,
  TextField,
  PasswordField,
  Button,
  useTheme,
} from '@aws-amplify/ui-react';

export const SignUpFormExample = () => {
  const { tokens } = useTheme();
  return (
    <Flex as="form" direction="column" gap={tokens.space.medium}>
      <Heading level={3}>Sign Up</Heading>
      <TextField label="Username" name="username" autoComplete="username" />
      <PasswordField
        label="Password"
        name="password"
        autoComplete="new-password"
        descriptiveText="Password must be at least 8 characters"
      />
      <Button type="submit" onClick={(e) => e.preventDefault()}>
        Sign Up
      </Button>
    </Flex>
  );
};

Login form example: current-password (default)

import {
  Button,
  Flex,
  Heading,
  PasswordField,
  TextField,
  useTheme,
} from '@aws-amplify/ui-react';

export const LoginFormExample = () => {
  const { tokens } = useTheme();
  return (
    <Flex as="form" direction="column" gap={tokens.space.medium}>
      <Heading level={3}>Login</Heading>
      <TextField label="Username" name="username" autoComplete="username" />
      <PasswordField
        label="Password"
        name="password"
        autoComplete="current-password"
      />
      <Button type="submit" onClick={(e) => e.preventDefault()}>
        Login
      </Button>
    </Flex>
  );
};

Change password example: current-password and new-password

import {
  Flex,
  Heading,
  TextField,
  PasswordField,
  Button,
  useTheme,
} from '@aws-amplify/ui-react';

export const ChangePasswordFormExample = () => {
  const { tokens } = useTheme();
  return (
    <Flex as="form" direction="column" gap={tokens.space.medium}>
      <Heading level={3}>Change Password</Heading>
      <TextField label="Username" name="username" autoComplete="username" />
      <PasswordField
        label="Current password"
        name="current_password"
        autoComplete="current-password"
        descriptiveText="Password must be at least 8 characters"
      />
      <PasswordField
        label="New password"
        name="new_password"
        autoComplete="new-password"
        descriptiveText="Password must be at least 8 characters"
      />
      <PasswordField
        label="Confirm password"
        name="confirm_password"
        autoComplete="new-password"
      />
      <Button type="submit" onClick={(e) => e.preventDefault()}>
        Submit
      </Button>
    </Flex>
  );
};

Accessibility / Label behavior

🚀

import { PasswordField, Text, Flex, useTheme } from '@aws-amplify/ui-react';

export const LabelHiddenExample = () => {
  const { tokens } = useTheme();
  return (
    <Flex>
      <Text paddingTop={tokens.space.small}>🚀</Text>
      <PasswordField label="Space Rocket Launch Codes" labelHidden={true} />
    </Flex>
  );
};

ShowPasswordButton

The ShowPasswordButton renders a <button> element with role="switch". Its aria-checked attribute is set to false when the password is hidden, and true when the password is shown.

There are several optional props for customizing the accessibility of the ShowPasswordButton:

showPasswordButtonLabel: Sets the aria-label for the ShowPasswordButton (defaults to "Show password")
passwordIsHiddenLabel: Sets the text read by screen readers when the password is hidden (defaults to "Password is hidden")
passwordIsShownLabel: Sets the text read by screen readers when the password is shown (defaults to "Password is shown")

Password

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

export const ShowPasswordButtonExample = () => {
  return (
    <PasswordField
      label="Password"
      showPasswordButtonLabel="Toggle password shown/hidden"
      passwordIsHiddenLabel="Your password is hidden"
      passwordIsShownLabel="Your password is shown"
    />
  );
};

Sizes

Use the size prop to change the visual size of the PasswordField. Three sizes are available: small, (default), and large.

Password

import { Flex, PasswordField, useTheme } from '@aws-amplify/ui-react';

export const SizeExample = () => {
  const { tokens } = useTheme();
  return (
    <Flex direction="column" gap={tokens.space.medium}>
      <PasswordField label="Password" name="password" size="small" />
      <PasswordField label="Password" name="password" />
      <PasswordField label="Password" name="password" size="large" />
    </Flex>
  );
};

Variations

There are two variation styles available: default and quiet.

Password

import { Flex, PasswordField, useTheme } from '@aws-amplify/ui-react';

export const VariationExample = () => {
  const { tokens } = useTheme();
  return (
    <Flex direction="column" gap={tokens.space.medium}>
      <PasswordField label="Password" name="password" />
      <PasswordField label="Password" name="password" variation="quiet" />
    </Flex>
  );
};

Descriptive text

To provide additional descriptive text of requirements of the field, use the descriptiveText field.

Password

Password length must be greater than 8 characters

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

export const DescriptiveTextExample = () => {
  const { tokens } = useTheme();
  return (
    <PasswordField
      label="Password"
      name="password"
      descriptiveText={
        <Text
          as="span"
          color="rebeccapurple"
          fontStyle="italic"
          fontSize={tokens.fontSizes.small}
        >
          Password length must be greater than 8 characters
        </Text>
      }
    />
  );
};

Required fields

Use the isRequired prop to specify a required field.

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

export const IsRequiredExample = () => {
  return (
    <Flex as="form" direction="column" width="20rem">
      <PasswordField label="Password" name="password" isRequired={true} />
      <Button type="submit">Submit</Button>
    </Flex>
  );
};

There is no default styling for required fields. Customize the label or descriptiveText to instruct the form user of the required field.

import { Flex, PasswordField, Text, Button } from '@aws-amplify/ui-react';

export const RequiredPasswordFieldExample = () => (
  <Flex as="form" direction="column" width="20rem">
    <PasswordField
      label={
        <Text>
          Password
          <Text as="span" fontSize="0.8rem" color="red">
            {' '}
            (required)
          </Text>
        </Text>
      }
      name="password"
      isRequired={true}
    />
    <PasswordField
      label="Password"
      descriptiveText={
        <Text as="span" fontSize="0.8rem" color="red" fontStyle="italic">
          Required
        </Text>
      }
      name="password"
      isRequired={true}
    />
    <Button type="submit">Submit</Button>
  </Flex>
);

Validation error styling

Use the hasError and errorMessage fields to mark a PasswordField as having a validation error.

Password

Requires uppercase, lowercase, and number with a minimum of 8 chars

import * as React from 'react';
import { Flex, PasswordField } from '@aws-amplify/ui-react';

export const ValidationErrorExample = () => {
  const [password, setPassword] = React.useState('1234');
  const validationRegex = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{8,}$/;
  const errorMessage = `Requires uppercase, lowercase, and number with a minimum of 8 chars`;
  return (
    <Flex gap="1rem" direction="column">
      <PasswordField
        onChange={(e) => {
          setPassword(e.target.value);
        }}
        label="Password"
        value={password}
        hasError={!validationRegex.test(password)}
        errorMessage={errorMessage}
      />
    </Flex>
  );
};

Forward refs

The standard ref prop will forward to the underlying input element, and the showPasswordButtonRef prop forwards to the show password button element.

The following is an example demonstrating use of the ref and showPasswordButtonRef props to put the focus on the password input field when the showPassword button is clicked:

Password

import * as React from 'react';
import { PasswordField } from '@aws-amplify/ui-react';

export const RefExample = () => {
  const inputRef = React.useRef(null);
  const showPasswordButtonRef = React.useRef(null);

  const onShowPasswordClick = React.useCallback(() => {
    inputRef.current.focus();
  }, []);

  React.useEffect(() => {
    const showPasswordButtonRefCurrent = showPasswordButtonRef.current;
    if (showPasswordButtonRefCurrent) {
      showPasswordButtonRefCurrent.addEventListener(
        'click',
        onShowPasswordClick,
        false
      );
      return () => {
        showPasswordButtonRefCurrent.removeEventListener(
          'click',
          onShowPasswordClick,
          false
        );
      };
    }
  }, [onShowPasswordClick]);

  return (
    <PasswordField
      label="Password"
      ref={inputRef}
      showPasswordButtonRef={showPasswordButtonRef}
    />
  );
};

Standard HTML attributes

The PasswordField will accept any of the standard HTML attributes that a <input> element accepts. Standard <input> attributes can be found in the MDN Documentation

Password

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

export const MaxLengthExample = () => {
  return <PasswordField label="Password" name="password" maxLength={10} />;
};

Styling

Theme

You can customize the appearance of all PasswordField components in your application with a Theme.

PasswordField Theme Source

Password

Password with Error

import {
  PasswordField,
  ThemeProvider,
  Theme,
  Button,
} from '@aws-amplify/ui-react';

const theme: Theme = {
  name: 'passwordfield-theme',
  tokens: {
    components: {
      passwordfield: {
        button: {
          color: { value: 'red' },
          _hover: {
            backgroundColor: { value: '{colors.blue.60}' },
            color: { value: 'white' },
          },
          _active: {
            backgroundColor: { value: '{colors.green.60}' },
            color: { value: 'white' },
          },
          _focus: {
            color: { value: 'white' },
          },
          _error: {
            backgroundColor: { value: 'orange' },
            _hover: { backgroundColor: { value: 'lavender' } },
            _focus: { borderColor: { value: 'green' } },
            _active: { borderColor: { value: 'white' } },
          },
        },
      },
      fieldcontrol: {
        borderColor: {
          value: '{colors.blue.60}',
        },
        color: {
          value: '{colors.red.80}',
        },
      },
    },
  },
};

export const PasswordFieldThemeExample = () => {
  return (
    <ThemeProvider theme={theme} colorMode="light">
      <PasswordField label="Password" />
      <PasswordField hasError={true} label="Password with Error" />
    </ThemeProvider>
  );
};

Icons

Password

import { PasswordField, IconsProvider } from '@aws-amplify/ui-react';
import { FiLock, FiUnlock } from 'react-icons/fi';

export const PasswordFieldIconExample = () => (
  <IconsProvider
    icons={{
      passwordField: {
        visibility: <FiLock />,
        visibilityOff: <FiUnlock />,
      },
    }}
  >
    <PasswordField label="Password" />
  </IconsProvider>
);

Target classes

Class	Description
`amplify-passwordfield`	Top level element that wraps the PasswordField primitive

--amplify-components-passwordfield-button-active-background-color
--amplify-components-passwordfield-button-active-border-color
--amplify-components-passwordfield-button-active-color
--amplify-components-passwordfield-button-color
--amplify-components-passwordfield-button-disabled-background-color
--amplify-components-passwordfield-button-disabled-border-color
--amplify-components-passwordfield-button-disabled-color
--amplify-components-passwordfield-button-error-active-background-color
--amplify-components-passwordfield-button-error-active-border-color
--amplify-components-passwordfield-button-error-active-color
--amplify-components-passwordfield-button-error-background-color
--amplify-components-passwordfield-button-error-border-color
--amplify-components-passwordfield-button-error-color
--amplify-components-passwordfield-button-error-focus-background-color
--amplify-components-passwordfield-button-error-focus-border-color
--amplify-components-passwordfield-button-error-focus-box-shadow
--amplify-components-passwordfield-button-error-focus-color
--amplify-components-passwordfield-button-error-hover-background-color
--amplify-components-passwordfield-button-error-hover-border-color
--amplify-components-passwordfield-button-error-hover-color
--amplify-components-passwordfield-button-focus-background-color
--amplify-components-passwordfield-button-focus-border-color
--amplify-components-passwordfield-button-focus-color
--amplify-components-passwordfield-button-hover-background-color
--amplify-components-passwordfield-button-hover-border-color
--amplify-components-passwordfield-button-hover-color
--amplify-components-passwordfield-color

Global styling

To override styling on all TextField primitives, you can set the Amplify CSS variables or use the built-in .amplify-textfield class.

Globally styled password field

/* styles.css */
[data-amplify-theme] {
  --amplify-components-field-border-color: var(--amplify-colors-purple-80);
}
/* OR */
.amplify-passwordfield {
  --amplify-components-field-border-color: var(--amplify-colors-purple-80);
}

Local styling

To override styling on a specific TextField, you can use a class selector or style props.

Using a class selector:

Square password field

/* styles.css */
.custom-passwordfield-class .amplify-input,
.custom-passwordfield-class .amplify-button {
  border-radius: 0;
}

Using style props:

Flex styling props will be applied to the PasswordField wrapping Flex component, whereas other style props will be applied to the input field. This allows us to change the layout of the label and input field, while also styling the input field directly.

Password:

Password

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

export const PasswordFieldStyledPropsExample = () => {
  const { tokens } = useTheme();
  return (
    <>
      <PasswordField
        label={
          <Text fontWeight="bold" fontSize={tokens.fontSizes.xl}>
            Password:
          </Text>
        }
        padding="xl"
        border={`1px solid ${tokens.colors.primary[60]}`}
      />
      <PasswordField
        label="Password"
        inputStyles={{
          backgroundColor: 'primary.10',
        }}
      />
    </>
  );
};