Migration

@aws-amplify/ui-react

Migrate from 5.x to 6.x

Installation

Install the 6.x version of both @aws-amplify/ui-react and aws-amplify.

Update and usage

@aws-amplify/ui-react@6.x introduces the following breaking changes:

1. Updates to the Authenticator

The initialState property now accepts forgotPassword in place of resetPassword:

- <Authenticator initialState="resetPassword" />
+ <Authenticator initialState="forgotPassword" />

The corresponding key of the components prop has been updated to reflect the change as well:

- <Authenticator components={{ ResetPassword: MyResetPassword }} />
+ <Authenticator components={{ ForgotPassword: MyForgotPassword }} />

The user object provided after an end user has been authenticated has been updated to reflect the AuthUser interface available from aws-amplify/auth:

- interface AmplifyUser {
-   challengeName?: ChallengeName;
-   attributes?: CognitoAttributes;
-   username: string;  
- }
+ interface AuthUser  {
+   username: string;
+   userId: string;
+   signInDetails?: CognitoAuthSignInDetails;
+ }

AuthUser can be imported from aws-amplify/auth:

import { AuthUser } from 'aws-amplify/auth';

User attributes are now available by directly calling fetchUserAttributes:

import { fetchUserAttributes } from 'aws-amplify/auth';

const userAttributes = await fetchUserAttributes();

The function signatures of the services interface have been updated to align with the shape of the underlying aws-amplify/auth APIs used by the Authenticator and provide improved typescript support:

interface AuthenticatorProps {
  services?: {
-    getCurrentUser?: () => Promise<any>,
+    getCurrentUser?: () => Promise<AuthUser>,

-    handleSignIn?: ({ username, password, }: { username: string;password: string; }) => Promise<any>,
+    handleSignIn?: (input: SignInInput) => Promise<SignInOutput>,

-    handleSignUp?: (formData: any) => Promise<ISignUpResult>,
+    handleSignUp?: (input: SignUpInput) => Promise<SignUpOutput>,

-    handleConfirmSignIn?: ({ user, code, mfaType, }: { user: any; code: string; mfaType: ChallengeName; }) =>Promise<any>),
+    handleConfirmSignIn?: (input: ConfirmSignInInput) => Promise<ConfirmSignInOutput>,

-    handleConfirmSignUp?: ({ username, code, }: { username: string; code: string; }) => Promise<any>,
+    handleConfirmSignUp?: (input: ConfirmSignUpInput) => Promise<ConfirmSignUpOutput>,

-    handleForgotPasswordSubmit?: ({ username, code, password, }: { username: string; code: string; password:string; }) => Promise<string>),
+    handleForgotPasswordSubmit?: (input: ConfirmResetPasswordInput) => Promise<void>,

-    handleForgotPassword?: (formData: any) => Promise<any>,
+    handleForgotPassword?: (input: ResetPasswordInput) => Promise<ResetPasswordOutput>,
  }
}

The input and return type interfaces are available as imports from aws-amplify/auth:

import { ConfirmSignInInput } from 'aws-amplify';

2. Expander is now Accordion

The Expander component has been replaced by the Accordion component in Amplify UI v6. The Accordion is fully composable and uses HTML elements <summary> and <details>.

<Expander type="single">
  <ExpanderItem title="Is it accessible?" value="demo-item-1">
    Yes! It adheres to the WAI-ARIA design pattern.
  </ExpanderItem>
  <ExpanderItem title="Can I customize the styling?" value="demo-item-2">
    Of course! See the section on CSS Styling below.
  </ExpanderItem>
  <ExpanderItem
    title="Is it a great way to organize content?"
    value="demo-item-3"
  >
    Most definitely!
  </ExpanderItem>
</Expander>

// Becomes 

<Accordion
  items={[
    {
      trigger: 'Is it accessible?',
      value: 'accessible',
      content: 'Yes! It uses HTML native elements: <details> and <summary>.'
    },
    {
      trigger: 'Can I customize the styling?',
      value: 'styling',
      content: 'Of course! See the section on CSS Styling below.'
    },
    {
      trigger: 'Is it a great way to organize content?',
      value: 'content',
      content: 'Most definitely!'
    }
  ]}
/>

The Accordion is also fully composable now too:

<Accordion.Container>
  <Accordion.Item value="Accordion-item">
    <Accordion.Trigger>
      What is an Accordion?
      <Accordion.Icon />
    </Accordion.Trigger>
    <Accordion.Content>
      An Accordion contains all the parts of a collapsible section.
    </Accordion.Content>
  </Accordion.Item>
  <Accordion.Item value="unique-value">
    <Accordion.Trigger>
      This is the item title
      <Accordion.Icon />
    </Accordion.Trigger>
    <Accordion.Content>
      The `children` of the Accordion are displayed here.
    </Accordion.Content>
  </Accordion.Item>
</Accordion.Container>

Behavior

Here are some differences in behavior between the Expander and Accordion components:

• The Accordion allows only 1 item expanded by default, while the Expander allowed multiple items expanded by default. To allow multiple open with Accordion, you need to add the allowMultiple prop.
• The Accordion cannot be fully collapsed by default, while the Expander could be collapsed. To make the Accordion always have 1 item open, use the preventCollapse prop.

Styling

The class names have changed between Expander and Accordion. Here is a mapping:

• amplify-expander -> amplify-accordion
• amplify-expander__item -> amplify-accordion__item
• amplify-expander__content -> amplify-accordion__content
• amplify-expander__header -> amplify-accordion__trigger
• amplify-expander__icon -> amplify-accordion__icon

The --amplify-components-accordion- CSS variables can also be used to style Accordion.

3. Tabs refactor

The Tabs component is now fully composable and more light-weight after removing the Radix dependency.

- import { Tabs, TabItem } from '@aws-amplify/ui-react'
+ import { Tabs } from '@aws-amplify/ui-react'

- <Tabs>
-  <TabItem title="Tab 1">
-    Tab 1 Content
-  </TabItem>

+ <Tabs.Container defaultValue="Tab 1">
+  <Tabs.List>
+    <Tabs.Item value="Tab 1">Tab 1</Tabs.Item>
+  </Tabs.List>
+  <Tabs.Panel value="Tab 1">
+    Tab 1 Content
+  </Tabs.Panel>

You can also use the Tabs in a uncomposed way too:

  <Tabs
    defaultValue={'Tab 1'}
    items={[
      { label: 'Tab 1', value: 'Tab 1', content: 'Tab content #1' },
      { label: 'Tab 2', value: 'Tab 2', content: 'Tab content #2' },
      { label: 'Tab 3', value: 'Tab 3', content: 'Tab content #3' },
    ]}
  />

Some notable differences:

• Instead of providing a defaultIndex or currentIndex you provide a defaultValue or value. Each Tabs.Item and Tabs.Panel should have a value that matches with the corresponding element.
• onChange becomes onValueChange
• You should supply a defaultValue or value or else there will be no default selected tab. Previously the Tabs component would default to the first tab.

There are also more design tokens and better CSS classes for easier customization.

4. Removal of extraneous data attributes and updating classNames

#4452

If you were using [data-] attributes in CSS to target styling components you will need to change these selectors to classes.

ClassName updates:

• amplify-loader__percentage-text -> amplify-loader__label
• amplify-menu-content-wrapper -> amplify-menu__wrapper
• amplify-menu-trigger -> amplify-menu__trigger
• amplify-menu-content -> amplify-menu__content
• amplify-menu-content__item -> amplify-menu__content__item
• amplify-pagination__item-button -> amplify-pagination__item
• amplify-pagination__item-current -> amplify-pagination__item--current
• amplify-pagination__item-ellipsis -> amplify-pagination__item--ellipsis
• amplify-rating-icon-container -> amplify-rating__item
• amplify-rating-icon -> amplify-rating__icon
• amplify-rating-icon-filled -> amplify-rating__icon--filled
• amplify-rating-icon-empty -> amplify-rating__icon--empty
• amplify-select__icon-wrapper -> amplify-select__icon
• .amplify-switch-label -> .amplify-switch__label
• .amplify-switch-thumb -> .amplify-switch__thumb
• .amplify-switch-track -> .amplify-switch__track

5. Moving brand.primary and brand.secondary up a level

To make it easier to access the primary and secondary colors in the Theme, we removed the brand namespace and moved primary and secondary up a level.

- tokens.colors.brand.primary[10]
+ tokens.colors.primary[10]

const theme = createTheme({
  tokens: {
    colors: {
-       brand: {
        primary: {
          //... 
        }
-       }
    }
  }
})

We also added the ability to easily set the entire range of primary and secondary colors at the theme level

const theme = createTheme({
  primaryColor: 'red',
  secondaryColor: 'green'
});

Migrate from 4.x to 5.x

Installation

Install the 5.x version of the @aws-amplify/ui-react library.

Update and usage

@aws-amplify/ui-react@5.x introduces the following breaking changes:

1. @aws-amplify/ui-react@5.x drops Amplify Geo components. They are moved to a separate new package @aws-amplify/ui-react-geo.

Install the 1.x version of the @aws-amplify/ui-react-geo library and update your existing imports accordingly.

Styles supporting Amplify Geo UI components are moved to @aws-amplify/ui-react-geo library and are not available through @aws-amplify/ui-react library anymore. When using components like MapView or LocationSearch from @aws-amplify/ui-react-geo library, import the styles from the same library as well.

import '@aws-amplify/ui-react-geo/styles.css';

For example, you can import the MapView component with related styles from @aws-amplify/ui-react-geo library.

import { Amplify } from 'aws-amplify';
import { MapView } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);

export default function BasicMap() {
  return <MapView />;
}

2. @aws-amplify/ui-react@5.x drops Amplify Notifications components. They are moved to a separate new package @aws-amplify/ui-react-notifications.

Install the 1.x version of the @aws-amplify/ui-react-notifications library and update your existing imports accordingly.

For example, you can import the In-App messaging components like InAppMessageDisplay and InAppMessagingProvider from @aws-amplify/ui-react-notifications library.

import { Text } from '@aws-amplify/ui-react';
import {
  InAppMessageDisplay
  InAppMessagingProvider,
} from '@aws-amplify/ui-react-notifications';

import '@aws-amplify/ui-react/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);

const App = () => {
  useEffect(() => {
    InAppMessaging.syncMessages();
  }, []);

  return (
    <InAppMessagingProvider>
      <InAppMessageDisplay />
      <Text>In-App Messaging Example</Text>
    </InAppMessagingProvider>
  );
};

3. @aws-amplify/ui-react@5.x removes the to prop from the Link component.

If using a Link component with the to prop, remove to and instead extend from the underlying rendered third-party Link. For example, using React Router Link with the Amplify UI Link component:

import { Link } from '@aws-amplify/ui-react';
import { Link as ReactRouterLink } from 'react-router-dom';

<Link as={ReactRouterLink} to="/">Home</Link>

4. @aws-amplify/ui-react@5.x updates component types to include the underlying rendered HTML element's attributes and strictly types the View component.

Migrate from 3.x to 4.x

Installation

Install the 4.x version of the @aws-amplify/ui-react library and the 5.x version of the aws-amplify library.

Update and usage

@aws-amplify/ui-react@4.x introduces the following breaking changes:

1. @aws-amplify/ui-react@4.x removes isMultiline prop from TextField.

Replace any TextField components using the isMultiline prop with the TextAreaField component.

- <TextField
-  isMultiline
+ <TextAreaField

2. @aws-amplify/ui-react@4.x moves text directionality support to ThemeProvider

@aws-amplify/ui-react has a dependency on Radix components for Menu, SliderField, Tabs, and Expander. There were a number of changes in the July 21, 2022 release of radix-ui/* packages, and the breaking change for @aws-amplify/ui-react was removal of support for the dir HTML attribute, and the addition of the DirectionProvider. In order to make the transition seamless for most of Amplify users, we've added the DirectionProvider with a default direction of ltr to the ThemeProvider.

If your application is using right to left directionality, the example below shows the needed change for apps using the native HTML dir="rtl":

- <View dir="rtl">
+ <ThemeProvider direction="rtl">

Also see: Internationalization

3. @aws-amplify/ui-react@4.x removes legacy component exports

The following deprecated components imported from @aws-amplify/ui-react/legacy are removed:

• AmplifyAuthenticator
• AmplifySignIn
• AmplifySignOut
• AmplifyChatbot
• AmplifyPhotoPicker
• AmplifyPicker
• AmplifyS3Album
• AmplifyS3Image
• AmplifyS3ImagePicker
• AmplifyS3Text
• AmplifyS3TextPicker
• withAuthenticator

Depending on the v1 version of this package and re-exporting these components caused issues. If you still want to use these legacy components you can depend on the v1 version of this package with an npm alias in your dependencies:

"@aws-amplify/ui-react-v1": "npm:@aws-amplify/ui-react@1.2.9"

Documentation for legacy components

4. @aws-amplify/ui-react@4.x adds inputStyles prop to Field primitives

Before 4.0, Field components like TextField would try to intelligently apply certain style props onto the wrapper element and some on the input element. We felt this was a little too opaque to users, but we still want to allow you to style the input element directly. @aws-amplify/ui-react@4.x adds an inputStyles prop to Field components so you can apply style props directly on the input (or textarea or select) as well as on the wrapper element.

Hopefully this change won't affect your code but will allow for more customization and control.

5. @aws-amplify/ui-react@4.x moves automatic signin on signup logic to aws-amplify.

If you are overriding Auth.signUp, update the override function call to include the autoSignIn option set to enabled. If this change is not made, users will not be automatically signed in on signup.

 async handleSignUp(formData) {
  let { username, password, attributes } = formData;
  // custom username
  username = username.toLowerCase();
  attributes.email = attributes.email.toLowerCase();
  return Auth.signUp({
    username,
    password,
    attributes,
+   autoSignIn: {
+     enabled: true
+   }
  });
}

6. @aws-amplify/ui-react@4.x removes legacy i18n translation keys removed

We replaced following legacy Authenticator texts:

• Forgot your password? with the trailing space is replaced by Forgot your password.

If you were using I18n to translate those keys, please update your translations accordingly to match the new strings.

Migrate from 2.x to 3.x

Installation

Install the 3.x version of the @aws-amplify/ui-react library.

Update and usage

@aws-amplify/ui-react@3.x introduces the following breaking changes:

1. @aws-amplify/ui-react@3.x removes the built-in icons (Icon360, IconSave, etc).

Replace any icon components in use the react-icons package or other React icon libraries in its place.

- import { IconSave } from '@aws-amplify/ui-react';
+ import { MdSave } from 'react-icons/md';

Note: We did not remove the Icon component, which allows customers to easily add SVG icons using the pathData prop.

2. @aws-amplify/ui-react@3.x removes ShareText.

This export has been removed and should no longer be used.

Migrate from 1.x to 2.x

Installation

Install the 2.x version of the @aws-amplify/ui-react library.

Update and Usage

Update the App.js with the new Authenticator and remove the old AmplifyAuthenticator as seen below:

App.js

- import { AmplifyAuthenticator, AmplifySignOut } from '@aws-amplify/ui-react';
import { Amplify } from 'aws-amplify';

+ import { Authenticator } from '@aws-amplify/ui-react';
+ import '@aws-amplify/ui-react/styles.css';

import awsExports from './aws-exports';
Amplify.configure(awsExports);

 const App = () => (
-  <AmplifyAuthenticator>
-    <div>
-      My App
-      <AmplifySignOut />
-    </div>
-  </AmplifyAuthenticator>
+  <Authenticator>
+      {({ signOut, user }) => (
+        <main>
+          <h1>Hello {user.username}</h1>
+          <button onClick={signOut}>Sign out</button>
+        </main>
+      )}
+    </Authenticator>
);

Authenticator breaking changes (1.x to 2.x)

The latest version of the Authenticator component has several differences from earlier versions. Here are a few of the major changes that you'll need to look out for.

Slots

All the slot locations have changed with the latest version of the Authenticator. To get a sense of the changes please check out the Headers and Footers section.

Form Fields

The latest version of the Authenticator has a different format for the formFields prop. It also no longer accepts inputProps nor hint. Instead, it's recommended that you use the Headers and Footers Slots or use the Sign Up Fields customization. For more information on form field customizations please see the Form Field Customization section.

CSS Styling

The latest version of the Authenticator has a completely different set of CSS variables. Please look over the Amplify CSS Variables section for more information.

onAuthUIStateChange

Previous versions of Authenticator exposed a onAuthUIStateChange handler to detect Auth state changes. For similar functionality see useAuthenticator.

@aws-amplify/ui-react-liveness

Migrate from 2.x to 3.x

Installation

Install the 3.x version of the @aws-amplify/ui-react-liveness library.

Update and Usage

Optionally update your App with the new prop usage:

App.js

 const App = () => (
  return (
    <ThemeProvider>
      {loading ? (
        <Loader />
      ) : (
        <FaceLivenessDetector
          sessionId={createLivenessApiData.sessionId}
          region="us-east-1"
          onAnalysisComplete={handleAnalysisComplete}
-         disableInstructionScreen={true}
+         disableStartScreen={true}
        />
      )}
    </ThemeProvider>
  );
);

CDN CSP Policy

The 3.x version of the FaceLivenessDetector has been updated to use the latest version of TensorFlow and Blazeface, thus the default CDN paths have changed. If your application has an existing CSP policy, ensure your policy allows https://cdn.liveness.rekognition.amazonaws.com. If you are using a custom CDN make sure to update your CDN versions to match @tensorflow/tfjs-backend-wasm and @tensorflow-models/face-detection.Please look over the Liveness Config section for more information.

Migrate from 1.x to 2.x

Installation

Install the 2.x version of the @aws-amplify/ui-react-liveness library.

Update and Usage

Optionally update your App with the new prop usage:

App.js

 const App = () => (
  return (
    <ThemeProvider>
      {loading ? (
        <Loader />
      ) : (
        <FaceLivenessDetector
          sessionId={createLivenessApiData.sessionId}
          region="us-east-1"
          onAnalysisComplete={handleAnalysisComplete}
-         onError={(error) => {
-           console.error(error);
-         }}
+         onError={(livenessError) => {
+           console.error({ state: livenessError.state, error: livenessError.error});
+         }}
        />
      )}
    </ThemeProvider>
  );
);

CDN CSP Policy

The 2.x version of the FaceLivenessDetector has updated the default CDN for TensorFlow and Blazeface to a new URL. If your application has an existing CSP policy, update your policy to allow https://cdn.liveness.rekognition.amazonaws.com. Please look over the Liveness Config section for more information.

@aws-amplify/ui-react-notifications

Installation

Install the 2.x version of @aws-amplify/ui-react-notifications and the 6.x version of aws-amplify.

Update and usage

@aws-amplify/ui-react-notifications@2.x introduces the following breaking changes:

Migrate from 1.x to 2.x

Starting with aws-amplify@6, the Notifications category is no longer exported from the base aws-amplify package. If you are using in-app messaging you will need to change your imports accordingly and run initializeInAppMessaging before your application code:

- import { Amplify, Notifications } from 'aws-amplify'
+ import { Amplify } from 'aws-amplify';
+ import { initializeInAppMessaging, syncMessages } from 'aws-amplify/in-app-messaging';
- import exports from './aws-exports';
+ import config from './amplifyconfiguration';

Amplify.configure(config);

- const { InAppMessaging } = Notifications;
+ initializeInAppMessaging()

const MyApp = () => {
  React.useEffect(() => {
-    InAppMessaging.syncMessages()
+    syncMessages();
  }, [])

  // ..
}

@aws-amplify/ui-react-storage

Migrate from 2.x to 3.x

Installation

Install the 3.x version of @aws-amplify/ui-react-storage and the 6.x version of aws-amplify.

Update and usage

@aws-amplify/ui-react-storage@3.x introduces the following breaking changes:

1. public accessLevel becomes 'guest' in Storage components

Starting in v6 of the Amplify JS libraries, 'public' access level, meaning unauthentiated users can access it, became 'guest'. The accessLevel property on FileUploader and StorageImage components have been updated to reflect this change.