You must render the <authenticator>
UI component before using the useAuthenticator
composable. useAuthenticator
was designed to retrieve <authenticator>
UI specific state such as route
and user
and should not be used without 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 theAuthenticator
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
.
Name | Description | Type |
---|---|---|
user | Current signed in user | AuthUser |
route | Name of the auth flow user is in | string |
error | Any error returned from service API call | string |
validationErrors | Any form validation errors found. Maps each error message to respective input name. | Record<string, string> |
hasValidationErrors | Whether there are any form validation errors | boolean |
isPending | Whether service API call is in progress | boolean |
codeDeliveryDetail | Provides 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.
Name | Description | Type |
---|---|---|
toSignIn | Transitions to signIn . Allowed from signUp , confirmSignUp , confirmSignIn , setupTotp , forgotPassword , and confirmResetPassword | () => void |
toSignUp | Transitions to signUp . Allowed from signIn . | () => void |
toForgotPassword | Transitions to forgotPassword . Allowed from signIn . | () => void |
toFederatedSignIn | Transitions to provider 's federated sign in page. Supported provider values can be found here. | (provider: string) => void |
skipVerification | Skips verification process. Allowed from verifyUser and confirmVerifyUser | () => void |