Advanced Usage

useAuthenticator

@aws-amplify/ui-svelte ships with useAuthenticator Svelte composable that can be used to access, modify, and update Authenticator's auth state.

<script lang="ts">
  import { Amplify } from 'aws-amplify';
  import { useAuthenticator } from '@aws-amplify/ui-svelte'
  import "@aws-amplify/ui-svelte/styles.css";
  import awsconfig from './aws-exports';
  import awsconfig from './amplify-output.json';

  const { authenticator } = $derived(useAuthenticator());
</script>

Note that the authenticator is an object wrapped with $state, meaning we cannot destructure it:

<script>
  import { useAuthenticator } from '@aws-amplify/ui-svelte';
  const { authenticator: { signOut } } = $derived(useAuthenticator());
  // ❌ This won't work because it breaks reactivity
</script>

In order to extract properties from the authenticator while keeping its reactivity, you need to use $derived.

<script setup>
  import { useAuthenticator } from '@aws-amplify/ui-svelte';
  // `route` `user` and `signOut` all are reactive.
  const { authenticator } = $derived(useAuthenticator());
  const { route, user, signOut } = $derived(authenticator);
</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
• selectMfaType
• setupEmail
• setupTotp
• forceNewPassword
• forgotPassword
• confirmResetPassword
• verifyUser
• confirmVerifyUser
• signOut
• authenticated

<script lang="ts">
  import { Authenticator, useAuthenticator } from '@aws-amplify/ui-svelte';
  const { authenticator } = $derived(useAuthenticator());
</script>

<Authenticator />
{#if authenticator.route === 'authenticated'}
  <button onclick={authenticator.signOut}>Sign out</button>
{/if}

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 lang="ts">
  import { Authenticator, useAuthenticator } from '@aws-amplify/ui-svelte';
  const { authenticator } = $derived(useAuthenticator());
</script>

<Authenticator />
{#if authenticator.authStatus === 'configuring'}
  <button onclick={authenticator.signOut}>Loading...</button>
{/if}
{#if authenticator.authStatus === 'authenticated'}
  <button onclick={authenticator.signOut}>Sign out</button>
{/if}

Access Authenticated User

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

<script>
  import { Authenticator, useAuthenticator } from '@aws-amplify/ui-svelte';
  const {authenticator: a } = $derived(useAuthenticator());
</script>

<Authenticator />
{#if a.route === 'authenticated'}
  <h1>Hello { a.user?.username }!</h1>
  <button onclick={a.signOut}>Sign out</button>
{/if}

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>
  import { Authenticator, useAuthenticator } from '@aws-amplify/ui-svelte';
  const {authenticator: a } = $derived(useAuthenticator());
</script>

<Authenticator />
{#if a.route === 'authenticated'}
  <h1>Hello { a.user?.username }!</h1>
  <button onclick={a.signOut}>Sign out</button>
{/if}

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 lang="ts">
  import { Authenticator, useAuthenticator } from '@aws-amplify/ui-svelte';
  import '@aws-amplify/ui-svelte/styles.css';

  const { authenticator: a } = $derived(useAuthenticator());
</script>

{#snippet signInFooter()}
  <div style="text-align: center">
    <button
      onclick={a.toForgotPassword}
      class="amplify-button amplify-field-group__control"
      data-fullwidth="false"
      data-size="small"
      type="button"
      style=" font-weight: normal"
    >
      Oh, no! Forgot Password?
    </button>
  </div>
{/snippet}

<Authenticator components={{
  SignIn: {
    Footer: signInFooter,
  },
}}>
  {#snippet children({ user, signOut })}
    <h1>Hello {user.username}!</h1>
    <button onclick={signOut}>Sign Out</button>
  {/snippet}
</Authenticator>

Full API