Advanced Usage

useAuthenticator Hook

@aws-amplify/ui-react-native ships with useAuthenticator React hook that can be used to access, modify, and update Authenticator's auth state. To use them, you must render the Authenticator and wrap your application with <Authenticator.Provider>:

import { Authenticator } from '@aws-amplify/ui-react-native';

export default () => (
  <Authenticator.Provider>
    <App />
  </Authenticator.Provider>
);

Then, you can use useAuthenticator on your App:

import { useAuthenticator } from '@aws-amplify/ui-react-native';

const App = () => {
  const { user, signOut } = useAuthenticator((context) => [context.user]);
  // ...
};

Authenticator Provider

In advanced use cases where usage of the useAuthenticator hook outside the scope of the Authenticator is needed, wrap your application inside an Authenticator.Provider. The Authenticator.Provider guarantees that the useAuthenticator hook is available throughout your application.

import { View, Text } from 'react-native';
import { Authenticator } from '@aws-amplify/ui-react-native';

export default function App() {
  return (
    <Authenticator.Provider>
      <View>
        <Text>Your app here</Text>
      </View>
    </Authenticator.Provider>
  );
};

Prevent Re-renders

Using useAuthenticator hook at your App level is risky, because it'll trigger a re-render down its tree whenever any of its context changes value.

To prevent undesired re-renders, you can pass a function to useAuthenticator that takes in Authenticator context and returns an array of desired context values. The hook will only trigger re-render if any of the array values change.

For example, you can ensure useAuthenticator to only reevaluate when its user context changes:

import { useAuthenticator } from '@aws-amplify/ui-react-native';

// hook below is only reevaluated when `user` changes
const { user, signOut } = useAuthenticator((context) => [context.user]);

Access Auth State

You can use useAuthenticator hook 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

import { useAuthenticator } from '@aws-amplify/ui-react-native';

const App = () => {
  const { route } = useAuthenticator(context => [context.route]);

  // Use the value of route to decide which page to render
  return route === 'authenticated' ? <Home /> : <Authenticator />;
};

Access Authenticated User

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

import { View, Text, Button } from 'react-native';
import { useAuthenticator } from '@aws-amplify/ui-react-native';

const Home = () => {
  const { user, signOut } = useAuthenticator((context) => [context.user]);

  return (
    <View>
      <Text>{`Welcome, ${user.username}!`}</Text>
      <Button onPress={signOut} title="Sign Out" />
    </View>
  );
};

Trigger Transitions

You can use useAuthenticator hook 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.

import { Button } from 'react-native';
import { useAuthenticator } from '@aws-amplify/ui-react-native';

const Home = () => {
  const { user, signOut } = useAuthenticator((context) => [context.user]);

  return <Button onPress={signOut} title={`Welcome, ${user.username}!`} />;
};

Example

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

import { View, Button, Text } from 'react-native';
import { Authenticator, useAuthenticator } from '@aws-amplify/ui-react-native';

function Footer() {
  const { toForgotPassword } = useAuthenticator();
  return (
    <Button onPress={toForgotPassword} title="Forgot Password???" />
  );
},

export default function App() {
  return (
    <Authenticator components={{
      SignIn: (props) => <Authenticator.SignIn {...props} Footer={Footer} />
    }}>
      <View>
        <Text>Hello {user.username}</Text>
        <Button onPress={signOut} title="Sign out" />
      </View>
    </Authenticator>
  );
}

Full API

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