From fba42492e0067c9e44cb53ff57397831c7339c94 Mon Sep 17 00:00:00 2001 From: Scott Rees <6165315+reesscot@users.noreply.github.com> Date: Thu, 18 Nov 2021 20:38:45 -0700 Subject: [PATCH] Port legacy amplify-ui-vue docs --- legacy/amplify-ui-vue/README.md | 1942 +++++++++++++++++++++++++++++++ 1 file changed, 1942 insertions(+) diff --git a/legacy/amplify-ui-vue/README.md b/legacy/amplify-ui-vue/README.md index c324e1663d0..1014fba845b 100644 --- a/legacy/amplify-ui-vue/README.md +++ b/legacy/amplify-ui-vue/README.md @@ -1 +1,1943 @@ # Amplify UI Vue + +Amplify UI Components is an open-source UI toolkit that encapsulates cloud-connected workflows inside of cross-framework UI components. + +## Installation + +``` +yarn add aws-amplify @aws-amplify/ui-components +``` + +# Authenticator + +A simple way to add authentication flows into your app is to use the Authenticator component. The Authenticator component encapsulates an authentication workflow in the framework of your choice and is backed by the cloud resources set up in your Auth cloud resources. + +# Authenticator + +## Usage + +### Recommended Usage + +In most cases you will need to manage the rendering and layout of the Authenticator separately. + +_App.vue_ + +```html + +``` + +Vue 3 + +```js +import { onAuthUIStateChange } from '@aws-amplify/ui-components'; + +export default { + name: 'AuthStateApp', + created() { + this.unsubscribeAuth = onAuthUIStateChange((authState, authData) => { + this.authState = authState; + this.user = authData; + }); + }, + data() { + return { + user: undefined, + authState: undefined, + unsubscribeAuth: undefined, + }; + }, + beforeUnmount() { + this.unsubscribeAuth(); + }, +}; +``` + +Vue 2 + +```js +import { onAuthUIStateChange } from '@aws-amplify/ui-components'; + +export default { + name: 'AuthStateApp', + created() { + this.unsubscribeAuth = onAuthUIStateChange((authState, authData) => { + this.authState = authState; + this.user = authData; + }); + }, + data() { + return { + user: undefined, + authState: undefined, + unsubscribeAuth: undefined, + }; + }, + beforeDestroy() { + this.unsubscribeAuth(); + }, +}; +``` + +_main.js_ (Vue 3) + +```js +import { createApp } from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +const app = createApp(App); +app.config.isCustomElement = (tag) => tag.startsWith('amplify-'); +app.mount('#app'); +``` + +_main.js_ (Vue 2) + +```js +import Vue from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +Vue.config.ignoredElements = [/amplify-\w*/]; + +new Vue({ + render: (h) => h(App), +}).$mount('#app'); +``` + +If you are using a build step to compile templates, you must configure `isCustomElement` option from the compiler configuration. You can use vue.config.js gist or vite.config.js gist to configure it for example. + +_App.vue_ + +```html + +``` + +To enable password manager, wrap the Authenticator component with `amplify-auth-container` component. + +```html + + + +``` + +

Properties

amplify-authenticator provides the following properties to configure the component.

federated
DescriptionFederated credentials & configuration.
TypeFederatedConfig
handleAuthStateChange
DescriptionCallback for Authenticator state machine changes
Type(nextAuthState: AuthState, data?: object) => void
Default() => {}
hideToast
Attributehide-toast
DescriptionHide amplify-toast for auth errors
Typeboolean
Defaultfalse
initialAuthState
Attributeinitial-auth-state
DescriptionInitial starting state of the Authenticator component. E.g. If `signup` is passed the default component is set to AmplifySignUp
TypeAuthState.ForgotPassword | AuthState.SignIn | AuthState.SignUp
DefaultAuthState.SignIn
usernameAlias
Attributeusername-alias
DescriptionUsername Alias is used to setup authentication with `username`, `email` or `phone_number`
Type"email" | "phone_number" | "username"
+ +

Slots

amplify-authenticator provides the following slots based off of the Web Components slot element.

NameDescription
confirm-sign-inContent placed inside of the confirm sign in workflow for when a user needs to confirm the account they signed in with
confirm-sign-upContent placed inside of the confirm sign up workflow for when a user needs to confirm the account they signed up with
forgot-passwordContent placed inside of the forgot password workflow for when a user wants to reset their password
greetingsContent placed inside of the greetings navigation for when a user is signed in
loadingContent placed inside of the loading workflow for when the app is loading
require-new-passwordContent placed inside of the require new password workflow for when a user is required to update their password
sign-inContent placed inside of the sign in workflow for when a user wants to sign into their account
sign-upContent placed inside of the sign up workflow for when a user wants to register a new account
totp-setupContent placed inside of the totp-setup workflow for when a user opts to use TOTP MFA
verify-contactContent placed inside of the verify-contact workflow for when a user must verify their contact information
+ +

Custom CSS Properties

amplify-authenticator provides the following css properties to modify the style at component level.

NameDescription
--background-colorBackground color of the container
--border-radiusBorder radius of the container
--box-shadowBow shadow of the container
--container-align`align-items` property of a flex container
--container-displayDisplay option of the container. Defaults to flex.
--container-heightHeight of the container. Defaults to 100vh.
--container-justify`justify-content` property of a flex container
--margin-bottomMargin below the component
--min-widthMinimum width of the container
--paddingPadding within the component
--widthWidth of the container
+ +## Customization + +### Custom Form Fields + +If you'd like to customize the form fields in the Authenticator Sign In or Sign Up component, you can do so by using the `formFields` property. + +The following example highlights the use of Authenticator with customized Sign Up form fields and [authentication with email](#authenticate-with-email-or-phone-number): + +```html + +``` + +If you have eslint-plugin-vue configured, it will suggest you to use v-slots on Vue 3 or later. This is applicable to Vue component slot specification but not the web component slots. You can disable this rule to avoid the error. + +```js + +``` + +If you are using the `usernameAlias` prop with custom `slots`, keep in mind that you must pass the `usernameAlias` prop value to both the Authenticator and custom slotted component since the slotted component overrides the configuration passed from the Authenticator. + +For more details on this customization see the `amplify-form-field` [prop documentation](https://github.com/aws-amplify/amplify-js/tree/main/packages/amplify-ui-components/src/components/amplify-form-field#properties) and the internal [`FormFieldType` interface](https://github.com/aws-amplify/amplify-js/blob/main/packages/amplify-ui-components/src/components/amplify-auth-fields/amplify-auth-fields-interface.ts#L3). + +### Hiding form fields + +Often you will not need a default form field, for example the phone number field. To implement this you can define the array of fields you'd like to show (along with the optional field customizations). + +In this example we are also managing the auth state to show and hide the Authenticator component based on the authenticated state of the user. This code will also persist the user sign in state on refresh. + +_App.vue_ + +```html + +``` + +Vue 3 + +```js +import { onAuthUIStateChange } from '@aws-amplify/ui-components' + +export default { + name: 'AuthStateApp', + created() { + this.unsubscribeAuth = onAuthUIStateChange((authState, authData) => { + this.authState = authState; + this.user = authData; + }) + }, + data() { + return { + user: undefined, + authState: undefined, + unsubscribeAuth: undefined + formFields: [ + { type: "username" }, + { type: "password" }, + { type: "email" } + ], + } + }, + beforeUnmount() { + this.unsubscribeAuth(); + } +} +``` + +Vue 2 + +```js +import { onAuthUIStateChange } from '@aws-amplify/ui-components'; + +export default { + name: 'AuthStateApp', + created() { + this.unsubscribeAuth = onAuthUIStateChange((authState, authData) => { + this.authState = authState; + this.user = authData; + }); + }, + data() { + return { + user: undefined, + authState: undefined, + unsubscribeAuth: undefined, + formFields: [ + { type: 'username' }, + { type: 'password' }, + { type: 'email' }, + ], + }; + }, + beforeDestroy() { + this.unsubscribeAuth(); + }, +}; +``` + +### Managing Layout with CSS + +Since the UI components are implemented using web components, you can control the top level `amplify-authenticator` component directly using CSS. + +```css +amplify-authenticator { + display: flex; + justify-content: center; + align-items: center; + flex: 1; + height: 100vh; +} +``` + +## Components + +### Sign In + +```html + + + +``` + +

Properties

amplify-sign-in provides the following properties to configure the component.

federated
DescriptionFederated credentials & configuration.
TypeFederatedConfig
formFields
DescriptionForm fields allows you to utilize our pre-built components such as username field, code field, password field, email field, etc. +by passing an array of strings that you would like the order of the form to be in. If you need more customization, such as changing +text for a label or adjust a placeholder, you can follow the structure below in order to do just that. +``` +[ + { + type: string, + label: string, + placeholder: string, + hint: string | Functional Component | null, + required: boolean + } +] +```
TypeFormFieldTypes | string[]
Default[]
handleAuthStateChange
DescriptionAuth state change handler for this component
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
handleSubmit
DescriptionFires when sign in form is submitted
Type(event: Event) => void
Defaultevent => this.signIn(event)
headerText
Attributeheader-text
DescriptionUsed for header text in sign in component
Typestring
DefaultTranslations.SIGN_IN_HEADER_TEXT
hideSignUp
Attributehide-sign-up
DescriptionHides the sign up link
Typeboolean
Defaultfalse
submitButtonText
Attributesubmit-button-text
DescriptionUsed for the submit button text in sign in component
Typestring
DefaultTranslations.SIGN_IN_ACTION
usernameAlias
Attributeusername-alias
DescriptionUsername Alias is used to setup authentication with `username`, `email` or `phone_number`
Type"email" | "phone_number" | "username"
Default'username'
+ +

Custom CSS Properties

amplify-sign-in provides the following css properties to modify the style at component level.

NameDescription
--footer-colorFont color of the footer
--footer-font-familyFont family of the footer
--footer-font-sizeFont size of the footer
--footer-weightFont weight of the footer
+ +

Slots

amplify-sign-in provides the following slots based off of the Web Components slot element.

NameDescription
federated-buttonsContent above form fields used for sign in federation buttons
footerContent is place in the footer of the component
header-subtitleSubtitle content placed below header text
primary-footer-contentContent placed on the right side of the footer
secondary-footer-contentContent placed on the left side of the footer
+ +### Sign Up + +**Usage** + +```html + + + +``` + +

Properties

amplify-sign-up provides the following properties to configure the component.

formFields
DescriptionForm fields allows you to utilize our pre-built components such as username field, code field, password field, email field, etc. +by passing an array of strings that you would like the order of the form to be in. If you need more customization, such as changing +text for a label or adjust a placeholder, you can follow the structure below in order to do just that. +``` +[ + { + type: string, + label: string, + placeholder: string, + hint: string | Functional Component | null, + required: boolean + } +] +```
TypeFormFieldTypes | string[]
Default[]
handleAuthStateChange
DescriptionAuth state change handler for this component +e.g. SignIn -> 'Create Account' link -> SignUp
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
handleSignUp
DescriptionOverride for handling the Auth.SignUp API call
Type(params: SignUpParams) => Promise<ISignUpResult>
Defaultparams => this.authSignUp(params)
handleSubmit
DescriptionFires when sign up form is submitted
Type(event: Event) => void
Defaultevent => this.signUp(event)
haveAccountText
Attributehave-account-text
DescriptionUsed for the submit button text in sign up component
Typestring
DefaultTranslations.SIGN_UP_HAVE_ACCOUNT_TEXT
headerText
Attributeheader-text
DescriptionUsed for header text in sign up component
Typestring
DefaultTranslations.SIGN_UP_HEADER_TEXT
signInText
Attributesign-in-text
DescriptionText used for the sign in hyperlink
Typestring
DefaultTranslations.SIGN_IN_TEXT
submitButtonText
Attributesubmit-button-text
DescriptionUsed for the submit button text in sign up component
Typestring
DefaultTranslations.SIGN_UP_SUBMIT_BUTTON_TEXT
usernameAlias
Attributeusername-alias
DescriptionUsername Alias is used to setup authentication with `username`, `email` or `phone_number`
Type"email" | "phone_number" | "username"
Default'username'
validationErrors
Attributevalidation-errors
DescriptionEngages when invalid actions occur, such as missing field, etc.
Typestring
+ +

Custom CSS Properties

amplify-sign-up provides the following css properties to modify the style at component level.

NameDescription
--footer-colorFont color of the footer
--footer-font-familyFont family of the footer
--footer-font-sizeFont size of the footer
--footer-weightFont weight of the footer
+ +

Slots

amplify-sign-up provides the following slots based off of the Web Components slot element.

NameDescription
footerContent placed in the footer of the component
header-subtitleSubtitle content placed below header text
primary-footer-contentContent placed on the right side of the footer
secondary-footer-contentContent placed on the left side of the footer
+ +### Sign Out + +**Usage** + +```html +
+ My App + +
+``` + +

Properties

amplify-sign-out provides the following properties to configure the component.

buttonText
Attributebutton-text
DescriptionText inside of the Sign Out button
Typestring
DefaultTranslations.SIGN_OUT
handleAuthStateChange
DescriptionAuth state change handler for this component
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
+ +

Slots

amplify-sign-out provides the following slots based off of the Web Components slot element.

NameDescription
sign-outThe sign out button element
+ +### Confirm Sign In + +```html + + + +``` + +

Properties

amplify-confirm-sign-in provides the following properties to configure the component.

formFields
DescriptionForm fields allows you to utilize our pre-built components such as username field, code field, password field, email field, etc. +by passing an array of strings that you would like the order of the form to be in. If you need more customization, such as changing +text for a label or adjust a placeholder, you can follow the structure below in order to do just that. +``` +[ + { + type: string, + label: string, + placeholder: string, + hint: string | Functional Component | null, + required: boolean + } +] +```
TypeFormFieldTypes | string[]
Defaultthis.defaultFormFields
handleAuthStateChange
DescriptionAuth state change handler for this component
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
handleSubmit
DescriptionFires when confirm sign in form is submitted
Type(event: Event) => void
Defaultevent => this.confirm(event)
headerText
Attributeheader-text
DescriptionUsed for header text in confirm sign in component
Typestring
DefaultTranslations.CONFIRM_SMS_CODE
submitButtonText
Attributesubmit-button-text
DescriptionUsed for the submit button text in confirm sign in component
Typestring
DefaultTranslations.CONFIRM
user
DescriptionCognito user signing in
TypeCognitoUserInterface
+ +### Confirm Sign Up + +```html + + + +``` + +

Properties

amplify-confirm-sign-up provides the following properties to configure the component.

formFields
DescriptionForm fields allows you to utilize our pre-built components such as username field, code field, password field, email field, etc. +by passing an array of strings that you would like the order of the form to be in. If you need more customization, such as changing +text for a label or adjust a placeholder, you can follow the structure below in order to do just that. +``` +[ + { + type: string, + label: string, + placeholder: string, + hint: string | Functional Component | null, + required: boolean + } +] +```
TypeFormFieldTypes | string[]
Default[]
handleAuthStateChange
DescriptionAuth state change handler for this components +e.g. SignIn -> 'Create Account' link -> SignUp
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
handleSubmit
DescriptionFires when sign up form is submitted
Type(submitEvent: Event) => void
Defaultevent => + this.confirmSignUp(event)
headerText
Attributeheader-text
DescriptionUsed for header text in confirm sign up component
Typestring
DefaultTranslations.CONFIRM_SIGN_UP_HEADER_TEXT
submitButtonText
Attributesubmit-button-text
DescriptionUsed for the submit button text in confirm sign up component
Typestring
DefaultTranslations.CONFIRM_SIGN_UP_SUBMIT_BUTTON_TEXT
user
DescriptionUsed for the username to be passed to resend code
TypeCognitoUserInterface
usernameAlias
Attributeusername-alias
DescriptionUsername Alias is used to setup authentication with `username`, `email` or `phone_number`
Type"email" | "phone_number" | "username"
Default'username'
+ +### Forgot Password + +```html + + + +``` + +

Properties

amplify-forgot-password provides the following properties to configure the component.

formFields
DescriptionThe form fields displayed inside of the forgot password form
TypeFormFieldTypes | string[]
Default[]
handleAuthStateChange
DescriptionAuth state change handler for this component
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
handleSend
DescriptionThe function called when making a request to reset password
Type(event: Event) => void
Defaultevent => this.send(event)
handleSubmit
DescriptionThe function called when submitting a new password
Type(event: Event) => void
Defaultevent => this.submit(event)
headerText
Attributeheader-text
DescriptionThe header text of the forgot password section
Typestring
DefaultTranslations.RESET_YOUR_PASSWORD
sendButtonText
Attributesend-button-text
DescriptionThe text displayed inside of the send code button for the form
Typestring
DefaultTranslations.SEND_CODE
submitButtonText
Attributesubmit-button-text
DescriptionThe text displayed inside of the submit button for the form
Typestring
DefaultTranslations.SUBMIT
usernameAlias
Attributeusername-alias
DescriptionUsername Alias is used to setup authentication with `username`, `email` or `phone_number`
Type"email" | "phone_number" | "username"
Default'username'
+ +### Require New Password + +```html + + + +``` + +

Properties

amplify-require-new-password provides the following properties to configure the component.

formFields
DescriptionThe form fields displayed inside of the forgot password form
TypeFormFieldTypes
Default[ + { + type: AuthFormField.Password, + required: true, + handleInputChange: event => this.handlePasswordChange(event), + label: I18n.get(Translations.NEW_PASSWORD_LABEL), + placeholder: I18n.get(Translations.NEW_PASSWORD_PLACEHOLDER), + inputProps: { + 'data-test': 'require-new-password-password-input', + }, + }, + ]
handleAuthStateChange
DescriptionAuth state change handler for this component
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
handleSubmit
DescriptionThe function called when submitting a new password
Type(event: Event) => void
Defaultevent => + this.completeNewPassword(event)
headerText
Attributeheader-text
DescriptionThe header text of the forgot password section
Typestring
DefaultTranslations.CHANGE_PASSWORD
submitButtonText
Attributesubmit-button-text
DescriptionThe text displayed inside of the submit button for the form
Typestring
DefaultTranslations.CHANGE_PASSWORD_ACTION
user
DescriptionUsed for the username to be passed to resend code
TypeCognitoUserInterface
+ +### TOTP Setup + +```html + + + +``` + +

Properties

amplify-totp-setup provides the following properties to configure the component.

handleAuthStateChange
DescriptionAuth state change handler for this component
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
handleComplete
DescriptionThis is run after totp setup is complete. Useful if using this as standalone.
Type(user: CognitoUserInterface) => void | Promise<void>
Defaultthis.onTOTPEvent
headerText
Attributeheader-text
DescriptionUsed for header text in totp setup component
Typestring
DefaultTranslations.TOTP_HEADER_TEXT
issuer
Attributeissuer
DescriptionUsed for customizing the issuer string in the qr code image
Typestring
DefaultTranslations.TOTP_ISSUER
standalone
Attributestandalone
DescriptionSet this to true if this component is running outside the default `amplify-authenticator` usage
Typeboolean
Defaultfalse
user
DescriptionUsed in order to configure TOTP for a user
TypeCognitoUserInterface
+ +### Verify Contact + +```html + + + +``` + +

Properties

amplify-verify-contact provides the following properties to configure the component.

handleAuthStateChange
DescriptionAuthentication state handler
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
user
DescriptionUser with unverified contact information
TypeCognitoUserInterface
+ +### Greetings + +_App.vue_ + +```html + +``` + +Vue 3 + +```js +import { onAuthUIStateChange } from '@aws-amplify/ui-components'; + +export default { + name: 'AuthStateApp', + created() { + this.unsubscribeAuth = onAuthUIStateChange((authState, authData) => { + this.authState = authState; + this.user = authData; + }); + }, + data() { + return { + user: undefined, + authState: undefined, + unsubscribeAuth: undefined, + }; + }, + beforeUnmount() { + this.unsubscribeAuth(); + }, +}; +``` + +Vue 2 + +```js +import { onAuthUIStateChange } from '@aws-amplify/ui-components'; + +export default { + name: 'AuthStateApp', + created() { + this.unsubscribeAuth = onAuthUIStateChange((authState, authData) => { + this.authState = authState; + this.user = authData; + }); + }, + data() { + return { + user: undefined, + authState: undefined, + unsubscribeAuth: undefined, + }; + }, + beforeDestroy() { + this.unsubscribeAuth(); + }, +}; +``` + +

Properties

amplify-greetings provides the following properties to configure the component.

handleAuthStateChange
DescriptionAuth state change handler for this component
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
logo
DescriptionLogo displayed inside of the header
TypeFunctionalComponent<{}>
Defaultnull
username
Attributeusername
DescriptionUsername displayed in the greetings
Typestring
Defaultnull
+ +

Custom CSS Properties

amplify-greetings provides the following css properties to modify the style at component level.

NameDescription
--background-colorBackground color of the container
--border-colorBorder color of the container
--font-familyFont family of the text
+ +

Slots

amplify-greetings provides the following slots based off of the Web Components slot element.

NameDescription
greetings-messageContent placed in the greetings text
logoLeft-justified content placed at the start of the greetings bar
navRight-justified content placed at the end of the greetings bar
+ +## Methods & Enums + +### AuthState + +`AuthState` is an enum with the following values: + +```js +enum AuthState { + SignUp = 'signup', + SignOut = 'signout', + SignIn = 'signin', + Loading = 'loading', + SignedOut = 'signedout', + SignedIn = 'signedin', + SigningUp = 'signingup', + ConfirmSignUp = 'confirmSignUp', + confirmingSignUpCustomFlow = 'confirmsignupcustomflow', + ConfirmSignIn = 'confirmSignIn', + confirmingSignInCustomFlow = 'confirmingsignincustomflow', + VerifyingAttributes = 'verifyingattributes', + ForgotPassword = 'forgotpassword', + ResetPassword = 'resettingpassword', + SettingMFA = 'settingMFA', + TOTPSetup = 'TOTPSetup', + CustomConfirmSignIn = 'customConfirmSignIn', + VerifyContact = 'verifyContact' +} +``` + +**Usage** + +```js +import { AuthState, onAuthUIStateChange } from '@aws-amplify/ui-components'; + +onAuthUIStateChange((nextAuthState, authData) => { + if (nextAuthState === AuthState.SignedIn) { + console.log('user successfully signed in!'); + } +}); +``` + +### onAuthUIStateChange + +`onAuthUIStateChange` is a function that will fire whenever the state of the Authentication UI component changes. + +**Usage** + +```js +import { AuthState, onAuthUIStateChange } from '@aws-amplify/ui-components'; + +onAuthUIStateChange((nextAuthState, authData) => { + if (nextAuthState === AuthState.SignedIn) { + console.log('user successfully signed in!'); + console.log('user data: ', authData); + } + if (!authData) { + console.log('user is not signed in...'); + } +}); +``` + +## Use Cases + +### Manage Auth State and Conditional app rendering + +_App.vue_ + +```html + +``` + +Vue 3 + +```js +import { onAuthUIStateChange } from '@aws-amplify/ui-components'; + +export default { + name: 'AuthStateApp', + created() { + this.unsubscribeAuth = onAuthUIStateChange((authState, authData) => { + this.authState = authState; + this.user = authData; + }); + }, + data() { + return { + user: undefined, + authState: undefined, + unsubscribeAuth: undefined, + }; + }, + beforeUnmount() { + this.unsubscribeAuth(); + }, +}; +``` + +Vue 2 + +```js +import { onAuthUIStateChange } from '@aws-amplify/ui-components'; + +export default { + name: 'AuthStateApp', + created() { + this.unsubscribeAuth = onAuthUIStateChange((authState, authData) => { + this.authState = authState; + this.user = authData; + }); + }, + data() { + return { + user: undefined, + authState: undefined, + unsubscribeAuth: undefined, + }; + }, + beforeDestroy() { + this.unsubscribeAuth(); + }, +}; +``` + +### Authenticate with email or phone number + +The `amplify-authenticator` component has the ability to sign in / sign up with `email` or `phone_number` instead of default `username`. + +To achieve this, you first need to setup the userpool to allow email or phone number as the username [using the cli workflow](/cli/auth/overview#configuring-auth-without-social-providers) or through the [Cognito Console](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#user-pool-settings-aliases-settings-option-2). To reflect this in the `amplify-authenticator` component, you can use the `usernameAlias` property. It can take one of the three values - `email`, `phone_number` or `username`. Default is set to `username`. + +```js + +``` + +### Override Sign Up + +You can override the call to [`signUp`](/lib/auth/emailpassword) function with `handleSignUp` property. For example, you can add a [custom attribute](https://docs.amplify.aws/lib/auth/emailpassword) like so: + +_App.vue_ + +```html + + +``` + +## Migration + +To migrate from using the `aws-amplify-` library to the latest `@aws-amplify/ui-` library use the steps below: + +### Installation + +```diff +- yarn add aws-amplify-vue ++ yarn add @aws-amplify/ui-components +``` + +_main.js_ + +Vue 3 + +```diff +import App from "./App.vue"; +- import Vue from 'vue'; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import { createApp } from 'vue'; ++ import { ++ applyPolyfills, ++ defineCustomElements, ++ } from '@aws-amplify/ui-components/loader'; +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +- new Vue({ +- render: h => h(App), +- }).$mount('#app'); ++ applyPolyfills().then(() => { ++ defineCustomElements(window); ++ }); ++ const app = createApp(App); ++ app.config.isCustomElement = tag => tag.startsWith('amplify-'); ++ app.mount('#app'); +``` + +Vue 2 + +```diff +import Vue from 'vue'; +import App from "./App.vue"; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import '@aws-amplify/ui-vue'; ++ import Amplify from 'aws-amplify'; ++ import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +new Vue({ + render: h => h(App), +}).$mount('#app'); +``` + +## Sign Out + +**Usage** + +```html + +``` + +

Properties

amplify-sign-out provides the following properties to configure the component.

buttonText
Attributebutton-text
DescriptionText inside of the Sign Out button
Typestring
DefaultTranslations.SIGN_OUT
handleAuthStateChange
DescriptionAuth state change handler for this component
Type(nextAuthState: AuthState, data?: object) => void
DefaultdispatchAuthStateChangeEvent
+ +

Slots

amplify-sign-out provides the following slots based off of the Web Components slot element.

NameDescription
sign-outThe sign out button element
+ +## Select MFA Type + +**Usage** + +```html + +``` + +

Properties

amplify-select-mfa-type provides the following properties to configure the component.

MFATypes
DescriptionTypes of MFA options
TypeMFATypesInterface
authData
DescriptionCurrent authenticated user in order to sign requests properly for TOTP
TypeCognitoUserInterface
handleSubmit
DescriptionFires when Verify is clicked
Type(event: Event) => void
Defaultevent => this.verify(event)
+ +--- + +# Interactions - Chatbot + +A simple way to add a conversational UI into your app is to use our ChatBot Component. + +ChatBot automatically renders a complete chat messaging interface that can be used out-of-the-box, or it can be customized using theming support. + +## Usage + +_main.js_ (Vue 3) + +```js +import { createApp } from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +const app = createApp(App); +app.config.isCustomElement = (tag) => tag.startsWith('amplify-'); +app.mount('#app'); +``` + +_main.js_ (Vue 2) + +```js +import Vue from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +Vue.config.ignoredElements = [/amplify-\w*/]; + +new Vue({ + render: (h) => h(App), +}).$mount('#app'); +``` + +If you are using a build step to compile templates, you must configure `isCustomElement` option from the compiler configuration. You can use vue.config.js gist or vite.config.js gist to configure it for example. + +_App.vue_ + +```html + +``` + +

Properties

amplify-chatbot provides the following properties to configure the component.

botName
Attributebot-name
DescriptionName of the bot
Typestring
botTitle
Attributebot-title
DescriptionText placed in the top header
Typestring
DefaultTranslations.CHATBOT_TITLE
clearOnComplete
Attributeclear-on-complete
DescriptionClear messages when conversation finishes
Typeboolean
Defaultfalse
conversationModeOn
Attributeconversation-mode-on
DescriptionContinue listening to users after they send the message
Typeboolean
Defaultfalse
silenceThreshold
Attributesilence-threshold
DescriptionNoise threshold between -1 and 1. Anything below is considered a silence.
Typenumber
Default0.2
silenceTime
Attributesilence-time
DescriptionAmount of silence (in ms) to wait for
Typenumber
Default1500
textEnabled
Attributetext-enabled
DescriptionWhether text chat is enabled
Typeboolean
Defaulttrue
voiceEnabled
Attributevoice-enabled
DescriptionWhether voice chat is enabled
Typeboolean
Defaultfalse
welcomeMessage
Attributewelcome-message
DescriptionGreeting message displayed to users
Typestring
+ + + + +```html + +``` + + + + +```html + +``` + +## Use Cases + +### Setting Up Voice Chat + +In order for voice input to work with Amazon Lex, you may have to enable output voice in [AWS Management Console](https://console.aws.amazon.com/console/home). Under the Amazon Lex service, click on your configured Lex chatbot and go to settings -> General and pick your desired output voice. + +### Listening to Chat Fulfillment + +Once a conversation session is finished, `amplify-chatbot` emits a custom event `chatCompleted` that your app can listen to: + +Vue 3 + +```html + +``` + +Vue 2 + +```html + +``` + +

Custom CSS Properties

amplify-chatbot provides the following css properties to modify the style at component level.

NameDescription
--bot-background-colorBackground color of bot messages
--bot-dot-colorBase color of bot loading message animation
--bot-text-colorText color of bot messages
--header-colorText color within the header
--header-sizeText size within the header
--heightHeight of the container
--user-background-colorBackground color of user messages
--user-dot-colorBase color of user loading message animation
--user-text-colorText color of user messages
--widthWidth of the container
+ +

Slots

amplify-chatbot provides the following slots based off of the Web Components slot element.

NameDescription
headerTitle content placed at the top
+ +## Migration + +To migrate from the legacy chatbot component to the latest chatbot component, use the steps below: + +### Installation + +Vue 3 + +```diff +- yarn add aws-amplify-vue ++ yarn add @aws-amplify/ui-components +``` + +Vue 2 + +```diff +- yarn add aws-amplify-vue ++ yarn add @aws-amplify/ui-vue +``` + +### Usage + +_main.js_ + +Vue 3 + +```diff +import App from "./App.vue"; +- import Vue from 'vue'; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import { createApp } from 'vue'; ++ import { ++ applyPolyfills, ++ defineCustomElements, ++ } from '@aws-amplify/ui-components/loader'; +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +- new Vue({ +- render: h => h(App), +- }).$mount('#app'); ++ applyPolyfills().then(() => { ++ defineCustomElements(window); ++ }); ++ const app = createApp(App); ++ app.config.isCustomElement = tag => tag.startsWith('amplify-'); ++ app.mount('#app'); +``` + +Vue 2 + +```diff +import Vue from 'vue'; +import App from "./App.vue"; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import '@aws-amplify/ui-vue'; ++ import Amplify from 'aws-amplify'; ++ import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +new Vue({ + render: h => h(App), +}).$mount('#app'); +``` + +--- + +# Storage - S3 Album + +## Usage + +_App.vue_ + +```html + +``` + +_main.js_ (Vue 3) + +```js +import { createApp } from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +const app = createApp(App); +app.config.isCustomElement = (tag) => tag.startsWith('amplify-'); +app.mount('#app'); +``` + +_main.js_ (Vue 2) + +```js +import Vue from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +Vue.config.ignoredElements = [/amplify-\w*/]; + +new Vue({ + render: (h) => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```html + +``` + +

Properties

amplify-s3-album provides the following properties to configure the component.

contentType
Attributecontent-type
DescriptionThe content type header used when uploading to S3
Typestring
Default'binary/octet-stream'
fileToKey
DescriptionCallback used to generate custom key value
Type(data: object) => string
filter
DescriptionFilter to be applied on album list
Type(list: StorageObject[]) => StorageObject[]
handleOnError
DescriptionFunction executed when error occurs for the s3-image
Type(event: Event) => void
handleOnLoad
DescriptionFunction executed when s3-image loads
Type(event: Event) => void
identityId
Attributeidentity-id
DescriptionCognito identity id of the another user's image list
Typestring
level
Attributelevel
DescriptionThe access level of the files
TypeAccessLevel.Private | AccessLevel.Protected | AccessLevel.Public
DefaultAccessLevel.Public
path
Attributepath
DescriptionString representing directory location of image files to be listed
Typestring
picker
Attributepicker
DescriptionBoolean to enable or disable picker
Typeboolean
Defaulttrue
pickerText
Attributepicker-text
DescriptionPicker button text
Typestring
DefaultTranslations.PICKER_TEXT
sort
DescriptionSort to be applied on album list
Type(list: StorageObject[]) => StorageObject[]
track
Attributetrack
DescriptionWhether or not to use track the get/put of the listing of images
Typeboolean
+ +

Custom CSS Properties

amplify-s3-album provides the following css properties to modify the style at component level.

NameDescription
--overlay-bg-colorImage overlay color on hover
+ +## Migration + +To migrate from using the `aws-amplify-` library to the latest `@aws-amplify/ui-` library use the steps below: + +### Installation + +```diff +- yarn add aws-amplify-vue ++ yarn add @aws-amplify/ui-components +``` + +_main.js_ + +Vue 3 + +```diff +import App from "./App.vue"; +- import Vue from 'vue'; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import { createApp } from 'vue'; ++ import { ++ applyPolyfills, ++ defineCustomElements, ++ } from '@aws-amplify/ui-components/loader'; +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +- new Vue({ +- render: h => h(App), +- }).$mount('#app'); ++ applyPolyfills().then(() => { ++ defineCustomElements(window); ++ }); ++ const app = createApp(App); ++ app.config.isCustomElement = tag => tag.startsWith('amplify-'); ++ app.mount('#app'); +``` + +Vue 2 + +```diff +import Vue from 'vue'; +import App from "./App.vue"; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import '@aws-amplify/ui-vue'; ++ import Amplify from 'aws-amplify'; ++ import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +new Vue({ + render: h => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```diff + +``` + +# Storage - S3 Image + +## Usage + +_App.vue_ + +```html + +``` + +_main.js_ (Vue 3) + +```js +import { createApp } from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +const app = createApp(App); +app.config.isCustomElement = (tag) => tag.startsWith('amplify-'); +app.mount('#app'); +``` + +_main.js_ (Vue 2) + +```js +import Vue from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +Vue.config.ignoredElements = [/amplify-\w*/]; + +new Vue({ + render: (h) => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```html + +``` + +

Properties

amplify-s3-image provides the following properties to configure the component.

alt
Attributealt
DescriptionString representing the alternate image text
Typestring
body
DescriptionImage body content to be uploaded
Typeobject
contentType
Attributecontent-type
DescriptionThe content type header used when uploading to S3
Typestring
Default'binary/octet-stream'
handleOnError
DescriptionFunction executed when error occurs for the image
Type(event: Event) => void
handleOnLoad
DescriptionFunction executed when image loads
Type(event: Event) => void
identityId
Attributeidentity-id
DescriptionCognito identity id of the another user's image
Typestring
imgKey
Attributeimg-key
DescriptionThe key of the image object in S3
Typestring
imgProps
DescriptionAttributes to be placed on the img element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attributes
Type{ [x: string]: any; [x: number]: any; }
level
Attributelevel
DescriptionThe access level of the image
TypeAccessLevel.Private | AccessLevel.Protected | AccessLevel.Public
DefaultAccessLevel.Public
path
Attributepath
DescriptionString representing directory location to image file
Typestring
track
Attributetrack
DescriptionWhether or not to use track on get/put of the image
Typeboolean
+ +

Custom CSS Properties

amplify-s3-image provides the following css properties to modify the style at component level.

NameDescription
--heightImage height
--widthImage width
+ +## Use Cases + +### Getting files from protected access level + +Protected files from S3 bucket can be accessed by anyone other than the owner by using the `identityId` of the owner. + +_App.vue_ + +```html + +``` + +## Migration + +To migrate from using the `aws-amplify-` library to the latest `@aws-amplify/ui-` library use the steps below: + +### Installation + +```diff +- yarn add aws-amplify-vue ++ yarn add @aws-amplify/ui-components +``` + +_main.js_ + +Vue 3 + +```diff +import App from "./App.vue"; +- import Vue from 'vue'; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import { createApp } from 'vue'; ++ import { ++ applyPolyfills, ++ defineCustomElements, ++ } from '@aws-amplify/ui-components/loader'; +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +- new Vue({ +- render: h => h(App), +- }).$mount('#app'); ++ applyPolyfills().then(() => { ++ defineCustomElements(window); ++ }); ++ const app = createApp(App); ++ app.config.isCustomElement = tag => tag.startsWith('amplify-'); ++ app.mount('#app'); +``` + +Vue 2 + +```diff +import Vue from 'vue'; +import App from "./App.vue"; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import '@aws-amplify/ui-vue'; ++ import Amplify from 'aws-amplify'; ++ import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +new Vue({ + render: h => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```diff + +``` + +If you were using S3Image with picker property enabled, please see the documentation for S3ImagePicker. + +# Storage - S3 Image Picker + +## Usage + +_main.js_ (Vue 3) + +```js +import { createApp } from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +const app = createApp(App); +app.config.isCustomElement = (tag) => tag.startsWith('amplify-'); +app.mount('#app'); +``` + +_main.js_ (Vue 2) + +```js +import Vue from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +Vue.config.ignoredElements = [/amplify-\w*/]; + +new Vue({ + render: (h) => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```html + +``` + +

Properties

amplify-s3-image-picker provides the following properties to configure the component.

buttonText
Attributebutton-text
DescriptionUpload Button Text as string
Typestring
DefaultTranslations.IMAGE_PICKER_BUTTON_TEXT
contentType
Attributecontent-type
DescriptionThe content type header used when uploading to S3
Typestring
Default'binary/octet-stream'
fileToKey
DescriptionCallback used to generate custom key value
Type(data: object) => string
headerHint
Attributeheader-hint
DescriptionHeader Hint value in string
Typestring
DefaultTranslations.IMAGE_PICKER_HINT
headerTitle
Attributeheader-title
DescriptionTitle string value
Typestring
DefaultTranslations.IMAGE_PICKER_TITLE
identityId
Attributeidentity-id
DescriptionCognito identity id of the another user's image
Typestring
level
Attributelevel
DescriptionThe access level of the image
TypeAccessLevel.Private | AccessLevel.Protected | AccessLevel.Public
DefaultAccessLevel.Public
path
Attributepath
DescriptionString representing directory location to image file
Typestring
placeholderHint
Attributeplaceholder-hint
DescriptionPlaceholder hint that goes under the placeholder image
Typestring
DefaultTranslations.IMAGE_PICKER_PLACEHOLDER_HINT
track
Attributetrack
DescriptionWhether or not to use track the get/put of the image
Typeboolean
+ +## Migration + +To migrate from using the `aws-amplify-` library to the latest `@aws-amplify/ui-` library use the steps below: + +### Installation + +```diff +- yarn add aws-amplify-vue ++ yarn add @aws-amplify/ui-components +``` + +_main.js_ + +Vue 3 + +```diff +import App from "./App.vue"; +- import Vue from 'vue'; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import { createApp } from 'vue'; ++ import { ++ applyPolyfills, ++ defineCustomElements, ++ } from '@aws-amplify/ui-components/loader'; +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +- new Vue({ +- render: h => h(App), +- }).$mount('#app'); ++ applyPolyfills().then(() => { ++ defineCustomElements(window); ++ }); ++ const app = createApp(App); ++ app.config.isCustomElement = tag => tag.startsWith('amplify-'); ++ app.mount('#app'); +``` + +Vue 2 + +```diff +import Vue from 'vue'; +import App from "./App.vue"; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import '@aws-amplify/ui-vue'; ++ import Amplify from 'aws-amplify'; ++ import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +new Vue({ + render: h => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```diff + +``` + +If you were using S3Image with picker property enabled, please see the documentation for S3ImagePicker. + +# Storage - S3 Text + +## Usage + +_main.js_ (Vue 3) + +```js +import { createApp } from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +const app = createApp(App); +app.config.isCustomElement = (tag) => tag.startsWith('amplify-'); +app.mount('#app'); +``` + +_main.js_ (Vue 2) + +```js +import Vue from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +Vue.config.ignoredElements = [/amplify-\w*/]; + +new Vue({ + render: (h) => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```html + +``` + +

Properties

amplify-s3-text provides the following properties to configure the component.

body
DescriptionText body content to be uploaded
Typeobject
contentType
Attributecontent-type
DescriptionThe content type header used when uploading to S3
Typestring
Default'text/*'
fallbackText
Attributefallback-text
DescriptionFallback content
Typestring
DefaultTranslations.TEXT_FALLBACK_CONTENT
identityId
Attributeidentity-id
DescriptionCognito identity id of the another user's text file
Typestring
level
Attributelevel
DescriptionThe access level of the text file
TypeAccessLevel.Private | AccessLevel.Protected | AccessLevel.Public
DefaultAccessLevel.Public
path
Attributepath
DescriptionString representing directory location to text file
Typestring
textKey
Attributetext-key
DescriptionThe key of the text object in S3
Typestring
track
Attributetrack
DescriptionWhether or not to use track the get/put of the text file
Typeboolean
+ +

Custom CSS Properties

amplify-s3-text provides the following css properties to modify the style at component level.

NameDescription
--border-colorBorder color of the text container
--container-colorBackground color of the text container
--font-sizeFont size of the text
--text-colorFont color of the text
+ +```css +amplify-s3-text { + --container-color: black; + --text-color: deepskyblue; +} +``` + +## Use Cases + +### Getting files from protected access level + +Protected files from S3 bucket can be accessed by anyone other than the owner by using the `identityId` of the owner. + +_App.vue_ + +```html + +``` + +## Migration + +To migrate from using the `aws-amplify-` library to the latest `@aws-amplify/ui-` library use the steps below: + +### Installation + +```diff +- yarn add aws-amplify-vue ++ yarn add @aws-amplify/ui-components +``` + +_main.js_ + +Vue 3 + +```diff +import App from "./App.vue"; +- import Vue from 'vue'; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import { createApp } from 'vue'; ++ import { ++ applyPolyfills, ++ defineCustomElements, ++ } from '@aws-amplify/ui-components/loader'; +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +- new Vue({ +- render: h => h(App), +- }).$mount('#app'); ++ applyPolyfills().then(() => { ++ defineCustomElements(window); ++ }); ++ const app = createApp(App); ++ app.config.isCustomElement = tag => tag.startsWith('amplify-'); ++ app.mount('#app'); +``` + +Vue 2 + +```diff +import Vue from 'vue'; +import App from "./App.vue"; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import '@aws-amplify/ui-vue'; ++ import Amplify from 'aws-amplify'; ++ import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +new Vue({ + render: h => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```diff + +``` + +If you were using S3Text with picker property enabled, please see the documentation for S3TextPicker. + +# Storage - S3 Text Picker + +## Usage + +_main.js_ (Vue 3) + +```js +import { createApp } from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +const app = createApp(App); +app.config.isCustomElement = (tag) => tag.startsWith('amplify-'); +app.mount('#app'); +``` + +_main.js_ (Vue 2) + +```js +import Vue from 'vue'; +import App from './App.vue'; +import { + applyPolyfills, + defineCustomElements, +} from '@aws-amplify/ui-components/loader'; + +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +applyPolyfills().then(() => { + defineCustomElements(window); +}); + +Vue.config.ignoredElements = [/amplify-\w*/]; + +new Vue({ + render: (h) => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```html + +``` + +

Properties

amplify-s3-text-picker provides the following properties to configure the component.

contentType
Attributecontent-type
DescriptionThe content type header used when uploading to S3
Typestring
Default'text/*'
fallbackText
Attributefallback-text
DescriptionFallback content for aplify-s3-text
Typestring
DefaultTranslations.PICKER_TEXT
fileToKey
DescriptionCallback used to generate custom key value
Type(data: object) => string
identityId
Attributeidentity-id
DescriptionCognito identity id of the another user's text file
Typestring
level
Attributelevel
DescriptionThe access level of the text file
TypeAccessLevel.Private | AccessLevel.Protected | AccessLevel.Public
DefaultAccessLevel.Public
path
Attributepath
DescriptionString representing directory location to text file
Typestring
track
Attributetrack
DescriptionWhether or not to use track the get/put of the text file
Typeboolean
+ +## Migration + +To migrate from using the `aws-amplify-` library to the latest `@aws-amplify/ui-` library use the steps below: + +### Installation + +```diff +- yarn add aws-amplify-vue ++ yarn add @aws-amplify/ui-components +``` + +_main.js_ + +Vue 3 + +```diff +import App from "./App.vue"; +- import Vue from 'vue'; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import { createApp } from 'vue'; ++ import { ++ applyPolyfills, ++ defineCustomElements, ++ } from '@aws-amplify/ui-components/loader'; +import Amplify from 'aws-amplify'; +import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +- new Vue({ +- render: h => h(App), +- }).$mount('#app'); ++ applyPolyfills().then(() => { ++ defineCustomElements(window); ++ }); ++ const app = createApp(App); ++ app.config.isCustomElement = tag => tag.startsWith('amplify-'); ++ app.mount('#app'); +``` + +Vue 2 + +```diff +import Vue from 'vue'; +import App from "./App.vue"; +- import Amplify, * as AmplifyModules from 'aws-amplify' +- import { AmplifyPlugin } from 'aws-amplify-vue' ++ import '@aws-amplify/ui-vue'; ++ import Amplify from 'aws-amplify'; ++ import awsconfig from './aws-exports'; + +Amplify.configure(awsconfig); + +new Vue({ + render: h => h(App), +}).$mount('#app'); +``` + +_App.vue_ + +```diff + +``` + +If you want to use S3Text without picker property enabled, please see the documentation for S3Text. + +# Storage - Tracking events + +You can automatically track `Storage` operations on the following components: `AmplifyS3Album`, `AmplifyS3Text`, `AmplifyS3Image`, `AmplifyS3TextPicker`, `AmplifyS3ImagePicker` by providing a `track` prop: + +```html + +``` + +Enabling tracking will automatically send 'Storage' events to Amazon Pinpoint, and you will be able to see the results in AWS Pinpoint console under _Custom Events_. The event name will be _Storage_, and event details will be displayed in _attributes_ , e.g. Storage -> Method -> Put. + +--- + +# Customization - Theming + +Theming for the UI components can be achieved by using CSS Variables. You can enable theming in your app by overriding the below mentioned CSS variable values. To do that, add the following code in root css file. + +``` +:root { + --amplify-primary-color: #ff6347; + --amplify-primary-tint: #ff7359; + --amplify-primary-shade: #e0573e; +} +``` + +## Supported CSS Custom properties + +### For Typography + +| Custom Properties | Default Value | +| ----------------------- | -------------------------------------------------------------------------------------------- | +| `--amplify-font-family` | 'Amazon Ember', 'Helvetica Neue Light', 'Helvetica Neue', 'Helvetica', 'Arial', 'sans-serif' | +| `--amplify-text-xxs` | 0.75rem | +| `--amplify-text-xs` | 0.81rem | +| `--amplify-text-sm` | 0.875rem | +| `--amplify-text-md` | 1rem | +| `--amplify-text-lg` | 1.5rem | +| `--amplify-text-xl` | 2rem | +| `--amplify-text-xxl` | 2.5rem | + +### For Colors + +| Custom Properties | Default Value | +| ------------------------------ | -------------------- | +| `--amplify-primary-color` | #ff9900 | +| `--amplify-primary-contrast` | var(--amplify-white) | +| `--amplify-primary-tint` | #ffac31 | +| `--amplify-primary-shade` | #e88b01 | +| `--amplify-secondary-color` | #152939 | +| `--amplify-secondary-contrast` | var(--amplify-white) | +| `--amplify-secondary-tint` | #31465f | +| `--amplify-secondary-shade` | #1F2A37 | +| `--amplify-tertiary-color` | #5d8aff | +| `--amplify-tertiary-contrast` | var(--amplify-white) | +| `--amplify-tertiary-tint` | #7da1ff | +| `--amplify-tertiary-shade` | #537BE5 | +| `--amplify-grey` | #828282 | +| `--amplify-light-grey` | #c4c4c4 | +| `--amplify-white` | #ffffff | +| `--amplify-red` | #dd3f5b | + +## Customizing CSS + +You can control top level components directly using CSS. For instance, to control the layout of the `amplify-authenticator`, we can specify the properties directly inside of its selector. + +```css +amplify-authenticator { + background: tomato; + padding: 5px; +} +``` + +The top level control is available for the following components. _**Note:**_ The components needs to be rolled out in the client in order to enable this CSS update. + +- `amplify-sign-in` +- `amplify-confirm-sign-in` +- `amplify-sign-up` +- `amplify-confirm-sign-up` +- `amplify-forgot-password` +- `amplify-require-new-password` +- `amplify-verify-contact` +- `amplify-totp-setup` + +## Translations + +Customizing text and adding language translations can be done via the `I18n` module: + +```js +import { I18n } from 'aws-amplify'; +import { Translations } from '@aws-amplify/ui-components'; + +I18n.putVocabulariesForLanguage('en-US', { + [Translations.SIGN_IN_HEADER_TEXT]: 'Custom Sign In Header Text', + [Translations.SIGN_IN_ACTION]: 'Custom Click Here to Sign In', +}); +``` + +A complete list of all translatable strings can be found in [`Translations.ts`](https://github.com/aws-amplify/amplify-js/blob/main/packages/amplify-ui-components/src/common/Translations.ts).