Amplify UI

Advanced Usage

Access Authenticator UI component state outside of the UI component

useAuthenticator

@aws-amplify/ui-vue ships with useAuthenticator Vue composable that can be used to access, modify, and update Authenticator's auth state. To use them, make sure the <authenticator> is present in the component or parent component:

<script setup>
  import { Authenticator, useAuthenticator } from '@aws-amplify/ui-vue';
  const auth = useAuthenticator();
</script>

<template>
  <authenticator></authenticator>
  <button @click="auth.signOut">Sign Out</button>
</template>

Note that the auth is an object wrapped with reactive, meaning there is no need to write .value after getters but, like props in setup, we cannot destructure it:

<script setup>
  import { Authenticator, useAuthenticator } from '@aws-amplify/ui-vue';
  const { signOut } = useAuthenticator();
  // ❌ This won't work because it breaks reactivity
  // it's the same as destructuring from `props`
</script>

In order to extract properties from the authenticator while keeping its reactivity, you need to use toRefs. It will create refs for any reactive property:

<script setup>
  import { toRefs } from 'vue';
  import { Authenticator, useAuthenticator } from '@aws-amplify/ui-vue';
  // `route` `user` and `signOut` all are reactive.
  const { route, user, signOut } = toRefs(useAuthenticator());
</script>

Access Auth State

You can use useAuthenticator composable to access route string that represents the current authState. They can be one of:

  • idle
  • setup
  • signIn
  • signUp
  • confirmSignIn
  • confirmSignUp
  • setupTotp
  • forceNewPassword
  • forgotPassword
  • confirmResetPassword
  • verifyUser
  • confirmVerifyUser
  • signOut
  • authenticated
<script setup> import { Authenticator, useAuthenticator } from '@aws-amplify/ui-vue'; const auth = useAuthenticator(); </script>
<template> <authenticator></authenticator>
<template v-if="auth.route === 'authenticated'">
<button @click="auth.signOut">Sign out</button>
</template>
</template>

Authentication Check

If you just need to check if you're authenticated or not, you can use the more straightforward useAuthenticator composable to access the authStatus string. The authStatus string can represent the following states:

  • configuring
  • authenticated
  • unauthenticated

The configuring state only occurs when the Authenticator is first loading.

<script setup> import { Authenticator, useAuthenticator } from '@aws-amplify/ui-vue'; const auth = useAuthenticator(); </script>
<template> <authenticator></authenticator>
<template v-if="auth.authStatus === 'configuring'">
<button @click="auth.signOut">Loading...</button>
</template>
<template v-if="auth.authStatus === 'authenticated'"> <button @click="auth.signOut">Sign out</button> </template> </template>

Access Authenticated User

You can use useAuthenticator composable to access current signed in user. If no user is authenticated, it'll return undefined.

<script setup> import { Authenticator, useAuthenticator } from '@aws-amplify/ui-vue'; const auth = useAuthenticator(); </script>
<template> <authenticator></authenticator>
<template v-if="auth.route === 'authenticated'">
<h1>Hello {{ auth.user?.username }}!</h1>
<button @click="auth.signOut">Sign out</button>
</template>
</template>

Trigger Transitions

You can use useAuthenticator composable to access functions that lets you trigger transitions to the authenticator. Please see Full API to see all supported transition functions. Any invalid transitions (e.g. signUp directly to authenticated) will be ignored.

<script setup> import { Authenticator, useAuthenticator } from '@aws-amplify/ui-vue'; const auth = useAuthenticator(); </script>
<template> <authenticator></authenticator>
<template v-if="auth.route === 'authenticated'">
<h1>Hello {{ auth.user?.username }}!</h1>
<button @click="auth.signOut">Sign out</button>
</template>
</template>

Example

Here's an example that uses the toForgotPassword trigger transition, to create a custom button. Note that example uses the Footer "slot" override.

<script setup lang="ts">
import { toRefs } from 'vue';
import { Authenticator, useAuthenticator } from '@aws-amplify/ui-vue';
import '@aws-amplify/ui-vue/styles.css';

const { toForgotPassword } = toRefs(useAuthenticator());
</script>

<template>
  <authenticator>
    <template v-slot:sign-in-footer>
      <div style="text-align: center">
<button @click="toForgotPassword" class="amplify-button amplify-field-group__control" data-fullwidth="false" data-size="small" type="button" style="font-weight: normal" >
Forgot Password???
</button>
</div> </template> </authenticator> </template>

Full API

Below is the full list of context that useAuthenticator composable returns.

These are readonly contexts that represent the current auth state. Any unapplicable context will be undefined.

NameDescriptionType
userCurrent signed in userAuthUser
routeName of the auth flow user is instring
errorAny error returned from service API callstring
validationErrorsAny form validation errors found. Maps each error message to respective input name.Record<string, string>
hasValidationErrorsWhether there are any form validation errorsboolean
isPendingWhether service API call is in progressboolean
codeDeliveryDetailProvides detail on where confirm sign up code is sent to.CodeDeliveryDetail

These helper functions trigger transition to another route. Note that any invalid transition (e.g. sign-in to authenticated directly) will be no-op.

NameDescriptionType
toSignInTransitions to signIn. Allowed from signUp, confirmSignUp, confirmSignIn, setupTotp, forgotPassword, and confirmResetPassword() => void
toSignUpTransitions to signUp. Allowed from signIn.() => void
toForgotPasswordTransitions to forgotPassword. Allowed from signIn.() => void
toFederatedSignInTransitions to provider's federated sign in page. Supported provider values can be found here.(provider: string) => void
skipVerificationSkips verification process. Allowed from verifyUser and confirmVerifyUser() => void

Amplify open source software, documentation and community are supported by Amazon Web Services.

© 2024 Amazon Web Services, Inc. and its affiliates. All rights reserved. View the site terms and privacy policy.

Flutter and the related logo are trademarks of Google LLC. We are not endorsed by or affiliated with Google LLC.