RFC: Amplify UI Component Library Refactor

[jordanranz]

This issue is a Request For Comments (RFC). It is intended to elicit community feedback regarding a proposed change to the Amplify JS UI components. Please feel free to post comments or questions here.

Current state of Amplify UI Components

Amplify JS currently provides a library of UI components intended to help developers leverage Amplify categories such as API, Auth, Storage, Interactions and XR. These UI components are implemented in different modules based on a particular frontend framework. Currently these frameworks include:

• React: aws-amplify-react
• React Native: aws-amplify-react-native
• Angular/Ionic: aws-amplify-angular
• Vue: aws-amplify-vue

The components provided by these modules are implemented in each respective JavaScript framework with duplicated logic. UI components are loosely styled using the Amplify UI style guide with some shared and some duplicated CSS. UI components are customizable but this functionality is limited and lacks parity between frameworks.

The Problem

This framework-specific approach has led to a variety of maintenance and extensibility challenges, including but not limited to:

• Lack of feature-parity across frameworks
• Duplication of code logic and developer efforts
• Divergent design patterns
• Ramp up for learning and maintaining multiple frameworks
• Inconsistent interaction and styling across frameworks
• Decreased developer velocity in creating new components
• Limited customizability of components

The Proposed Solution

Overview

Currently, we plan to implement an Amplify UI design system using Web Components generated by StencilJS. We plan to refactor the current framework-specific component logic to alternatively use the logic implemented inside of web components from this design system.

Additionally, we will utilize CSS-in-JS to create a more flexible customization and theming strategy for components. We are evaluating the use of Emotion to build this strategy into our web components.

This approach has a number of benefits associated with it, including but not limited to:

• Reduced code base
• Faster iteration on enhancements, new features and new components
• Greater accessibility for Amplify users working with frameworks other than React, Angular, Ionic, Vue, or those using no framework at all
• More flexible and consistent styling pattern
• Improved developer experience and code quality

Design Requirements

• Components should be useable within our currently supported browser-based frameworks (React, Angular, Vue) with little-to-no friction for developers using Amplify JS. This could conceivably entail the creation of framework-specific wrappers for the components, but at this time it is thought that Stencil generated web components should suffice.
• Components must be functional within other web components, UI frameworks, and plain HTML/JS pages.
• This project should offer feature parity with the sum of functionality between our existing UI packages; in other words, developers currently operating within a given framework should not find that they have lost capabilities upon migration.
• Components should be responsive.
• Components should be customizable and themeable. For example, users of an 'Authenticator' component should be able to define their 'Sign-In' child component which uses their own markup and styling, but which seamless integrates with the out-of-the-box behavior of the Authenticator.
• All efforts should be taken to maintain as small a bundle size as possible.
• Components should be Typescript-compatible with well-defined and understandable typings.
• Components must be compatible with AWS supported browsers.
• SSR (Server Side Rendering) of Amplify UI components should be supported

Related Github Issues

Customizable components

• Add attribute for isSignInDisplayed to config for amplify-sign-up (Add attribute for isSignInDisplayed to config for amplify-sign-up #3216)
• Feature request: PhotoPicker should allow setting id (https://github.com/aws-amplify/amplify-js/issues/3196)
• Direct routeLink to subforms of (https://github.com/aws-amplify/amplify-js/issues/3191)
• Vue Authenticator Component missing theme integration (Vue Authenticator Component missing theme integration #3068)
• Forgot Password? text should be clickable (Forgot Password? text should be clickable #3046)
• Allow theming for select elements (Allow theming for select elements #2994)
• Angular theme suport (Angular theme suport  #2750)
• Customize amplify-react Greetings className not update to Nav #help wanted (Customize amplify-react Greetings className not update to Nav #help wanted #2672)
• [Vue] How to safely override Amplify built-in components via CSS? ([Vue] How to safely override Amplify built-in components via CSS? #2471)
• Provide a function to customize error message (Provide a function to customize error message #2104)
• Customize AWS Amplify Authenticator UI for Angular (Customize AWS Amplify Authenticator UI for Angular #2075)
• Theme not available on amplify-angular (Theme not available on amplify-angular  #1755)
• how can we style/scale the image displayed by component for React ? (how can we style/scale the image displayed by <S3Image> component for React ?  #1655)
• React customize-withauthenticator doesnt work on v2.0.0-2.0.1 (React customize-withauthenticator doesnt work on v2.0.0-2.0.1 #1603)
• Custom UI withAuthenticator (Custom UI withAuthenticator #1436)
• Increase theme-bility in Ionic 4 (https://github.com/aws-amplify/amplify-js/issues/1358)
• Passing down className prop in S3Image component (Passing down className prop in S3Image component #1272)
• Is it possible to customize default Sign Up, Sign In screens of aws-amplify-react-native package? (Is it possible to customize default Sign Up, Sign In screens of aws-amplify-react-native package? #1031)
• RFC: react component HOCs allowing for bringing your own component (RFC: react component HOCs allowing for bringing your own component #940)
• RFC: Authenticator render props (RFC: Authenticator render props #474)
• Can I validate user input w/o subsequent signup? Only validation (Can I validate user input w/o subsequent signup? Only validation #1054)

Component improvements

• Angular authenticator sign in fill login form (Angular authenticator sign in fill login form #3050)
• amplify-authenticator angular adding rememberme (amplify-authenticator angular adding rememberme #3010)
• aws-amplify-react: User cannot be confirm. Current status is CONFIRMED (https://github.com/aws-amplify/amplify-js/issues/2797)
• Federated sign-in buttons have broken styles. (Federated sign-in buttons have broken styles. #2752)
• How to disable Amplify from loading its Auth CSS theme file in a React app? (How to disable Amplify from loading its Auth CSS theme file in a React app? #2691)
• React Native Amplify UI: Phone Number Country Code is forced to be a Picker (https://github.com/aws-amplify/amplify-js/issues/2632)
• Auto signin after confirm email (Auto signin after confirm email #2562)
• [Vue] Auth, password not contained within a form element ([Vue] Auth, password not contained within a form element #2479)
• Could not find a declaration file for module '@aws-amplify/ui' (Could not find a declaration file for module '@aws-amplify/ui' #2460)
• password weakness warning is unclear (<amplify-authenticator> password weakness warning is unclear #2416)
• Allow null as default for countryCode in signup components (Allow null as default for countryCode in signup components #2327)
• Add loading indicator to Authenticator components (Add loading indicator to Authenticator components #2311)
• importing 'aws-amplify-react', ERROR: Uncaught SyntaxError: Unexpected token : (importing 'aws-amplify-react', ERROR: Uncaught SyntaxError: Unexpected token : #2230)
• Make React Authenticator CSS class names customization friendly (Make React Authenticator CSS class names customization friendly #2161)
• Getting error when implement to nextJs (Getting error when implement to nextJs #1963)
• authentication ui (authentication ui #404)
• S3Image component ignores preview="hidden" if path prop specified (S3Image component ignores preview="hidden" if path prop specified #218)
• aws-amplify-react-native UI Components (aws-amplify-react-native UI Components #2725)
• Add Auth to React context using Provider pattern (https://github.com/aws-amplify/amplify-js/issues/3090)
• Verify Contact flow for logged-in user (Reusing the VerifyContact component #4503)

Related milestone: https://github.com/aws-amplify/amplify-js/milestone/13

[ajhool]

Note: all experience has been with the React components.

I'm glad to see that the team will refactor these components.

1. Please try to add SSR compatibility into any new additions to Amplify. It does not need to actually render on the server, but please ensure that it does not break SSR. Currently the React Authenticator component breaks SSR and requires fragile workarounds

2. The documentation is currently too sparse and unorganized. The documentation is all example-based and I've had trouble finding an explanation a simple, plain reference for the various props. The Authenticator props and design choices, in particular, are strange and unintuitive, so that component has been frustrating to work with despite being (arguably) the most important UI in any application.

3. Typescript instead of javascript

4. The Authenticator component requires passing in Components to the "hide" prop (eg. <Greetings />, <Loading />). It would be nice to just be able to pass in strings, (eg. ["loading", "greetings"]).

5. Perhaps this is a more broad critique, but sometimes Amplify/AWS moves at break-neck speed to add features horizontally while leaving behind inexplicable functionality holes in core components. For instance, issue Support for email-only SignUp through withAuthenticator #104 (enable sign up using only email + password) hasn't been addressed in a year in a half. This framework has support for Alexa voice commands, but not login with email + password, that's hard to understand.

6. Currently, the "Sign Up" Authenticator panel does not include the federated login buttons, but I believe that it should. Standard modern auth flow is to show the "Sign Up" panel as the default and encourage users to sign up with social login. If a user already has an account, they click the "I already have an account" button at the bottom.

[jordanranz]

Hey @ajhool,

Thank you for the feedback.

1. Creating a smooth interaction for SSR is one of design requirements for this project. I have added this to the design requirements listed above. Using both StencilJS and Emotion should help us achieve this goal.

2. Documentation will definitely be refactored over the course of this project. One big improvement we are looking to make comes with introducing the use of Storybook to our documentation. This will provide a lot more clarity to a user on how to use the component API and also even allow them to test the functionality our components.

3. There is a design requirement to make this happen: "Components should be Typescript-compatible with well-defined and understandable typings". StencilJS generated web components are typed out-of-the-box, so this should be fairly straightforward with the current development plan.

4. I will make note of this feedback and refer to it when building the new Authenticator web component. Passing a string array is a good idea but maintaining a string to component mapping might not be the most scalable option. Definitely something to look into more.

5. Noted. This feedback is more focused toward the library/organization but we will definitely take this into account moving forward. Also FYI there is a PR for that specific callout: Sign up with email #3103 :)

6. Good comments and feedback. We can evaluate this when creating the new Authenticator component. Maybe have this order configurable where you can choose the order of your Authenticator flow (i.e Sign-up first, with a "I already have an account" link or Sign-in first, with an account sign up link).

[ajhool]

Thanks for the response and I look forward to contributing towards Storybook integration and Typescript compatibility, these are excellent tools!

Would it be helpful if I created a Storybook integration for the existing UI components? If so, would the team accept the use of typescript to build the storybook?

[jordanranz]

We would greatly appreciate the contribution of Storybook integration with our existing UI components and accept the use of Typescript to build this!

If this is something you would like to contribute, you can open a new issue to track this feature request/implementation and reference this RFC.

[clementAC]

Same note as @ajhool

Hi,

I agree with ajhool on all the points.

The doc is really great for a beginner with lot of exemples but once you try to make more complex uses cases there are some important points and props that are not documented. And searching in source code is quite annoying. Storybook or a similar product could be a good solution

I also agree on the amplify lib development "break-neck" thing. Sometimes I'm completely wondering why a feature is not implemented whereas it's a typical use case for a website. For instance, user administration, choose on wich s3 bucket I want to upload my files (default one or another one) and lot more and i'm not talking about visual components.
I know that amplify is created for simplifying aws services access and adoption (and it manage to do it) but if the classical use cases are not taken into account then the point is completelly missed and sometimes amplify is making the service access more "frictional".

Everytime amplify is updated I'm wondering what have changed. With this new approach it could be an excellent idea to implement a changelog system. It will sure avoid some side effects du to upgrading the library in the future.

During the last month amplify have changed a lot and I think this proposition of refactoring is a great news for amplify developers and users.

[ajhool]

Have started a storybook integration here: https://github.com/ajhool/amplify-js . If anybody is available from the Amplify team for a quick realtime chat this week to help me get oriented, I'd really appreciate it. After that, it should be ("should") relatively straightforward to build stories for each component

[m8schmit]

Hi, following the discussion here : #4515 (comment)

can you add this to your things to do on amplify-ui :
currently you use var() to handle colors but the css variables aren't supported by IE11.

(@ericclemmons, tell me if it's enough or if i have to open a specific issue and link it here. )

Thanks !

[Rafcin]

This probably isn't right but as of now I think in terms of signup/signin forms aren't all bad. The default auth ui sucks but you can easily make your own! I Found using formik works well for auth forms, it's simple where you can make checks for basic things like "is it an email" or "is it a zipcode", but what I think would be nice is a way to check something like isValidPassword() for when you login because while the auth form handles all this, not all people want to use it. In my case I use filepond for uploading files, and I can't do that with the auth form, so these tiny details would be nice.

Or add a component that's highly customizable.

A side suggestion would be to change the community channel Glitter to something like Slack. One major problem is if you want to search something it's almost impossible on Glitter. Some things on the wiki are not up to date or complex and when someone explains it it's impossible to find and or the chat is dead and no one really has a solution. I think Slack or some other program would be nice and it would allow us to easily communicate, possibly track issues from Slack or discuss problems and solutions with AWS devs and the community.

[mayteio]

Is there a list of issues related to this RFC, or is it still in discussion? I'd love to start contributing and it would be awesome if related issues could be triaged with a label for it and good-first-issues too.

[ProdigySim]

We used amplify-react, then amplify-react-native, and then built a custom UI for the next project.

There are so few AmplifyJS API calls needed for each auth component that I'd rather see good documentation on how to set up an "Authenticator" yourself. Handling auth state changes + specific API calls to do Signin, forgot password, etc.

Building a signin form is not hard. Handling Amplify's auth flows properly is. Help us model our UI in the correct form, but don't make us try to customize a premade one.

[jordanranz]

Amplify UI Component (Preview)

Hello all,

Wanted to provide an update on the status for this project and give an overview of the phases we are planning on releasing in the near future. As mentioned above in this RFC the problems we wanted to solve for this project included:

• Lack of feature-parity across frameworks
• Duplication of code logic and developer efforts
• Divergent design patterns
• Ramp up for learning and maintaining multiple frameworks
• Inconsistent interaction and styling across frameworks
• Decreased developer velocity in creating new components
• Limited customizability of components

Phase 1

In Phase 1 of this project we will seek to solve or at least alleviate all of the problems listed above. To achieve this we will be releasing a brand new web component library and new libraries for each of the frameworks that we currently support. The framework libraries will include React, Angular, and Vue and these will be generated based off of the code in the core web components library. The original component libraries offered in the current release of amplify-js will go into maintenance mode and we will no longer be adding features to these libraries. For customers using the original React, Angular, or Vue component libraries, we will be providing migration guides for those looking to migrate to using the new components. Phase 1 is complete when we are at feature parity with the original UI component libraries.

Here is a breakdown of the new libraries being added:

Framework	Package	Version
React	@aws-amplify/ui-react
Angular	@aws-amplify/ui-angular
Vue	@aws-amplify/ui-vue
Web Components	@aws-amplify/ui-components

The amplify-authenticator component is currently available for preview using the tag ui-preview. For more information about using the new amplify-authenticator component and getting started with the Amplify UI Component library check out the README here.

For feedback and feature requests related to this preview release please open a new issue in our issue queue and add the label: Amplify UI Components. Also, feel free to comment below on this RFC.

Phase 2

Once our new UI component libraries are at feature parity with the original libraries, we will move on to Phase 2. In this phase we will be looking to address the comments and requests presented in this RFC. I really like the ideas presented here especially the one about offering an AuthProvider “renderless” component mentioned in @Bruqui‘s comment. Interactive and better documentation as @ajhool mentioned is also something we will be looking to support.

In addition to addressing the comments in this RFC, we will also be doing a retro on the issues and feature requests in our queue related to UI components. This milestone will be used to track the progress for these.

Phase 2 may also include new components from other Amplify categories like Predictions or API. If anyone would like to contribute ideas to what components you’d like to see added in the future please post it in this RFC or open a new feature request with the Amplify UI Components label!

Thank you!

The feedback that you all give is extremely helpful and gives us a better understanding of what people want us to build. Go ahead and try out the new component libraries and let us know what you think.

[jordanranz]

The Phase 1 of the post I made above has been released for the Auth category components!

Here is the blog post:
https://aws.amazon.com/blogs/mobile/amplify-framework-announces-new-rearchitected-ui-component-and-modular-javascript-libraries/

Here is our new preview Docs:
https://docs.amplify.aws/ui

We will now be working on adding additional category support for Storage, API, etc. and then moving on to Phase 2. I am going to close this RFC now. Thank you everyone for the feedback on this Issue!

Cheers 🍻

[github-actions]

This issue has been automatically locked since there hasn't been any recent activity after it was closed. Please open a new issue for related bugs.

Looking for a help forum? We recommend joining the Amplify Community Discord server *-help channels or Discussions for those types of questions.