Skip to content

Authentication with our UI components

Account Kit allows you to use pre-built, highly customizable UI components to handle authenticating your users. These components provide flexibility to:

Modal auth

Assuming your application has been set up, using UI components is the easiest way to authenticate users. All you have to do is leverage the useAuthModal hook and provide users a CTA to open the modal.

import React from "react";
import { useAuthModal } from "@account-kit/react";
 
export default function MyPage() {
  const { openAuthModal } = useAuthModal();
 
  return <button onClick={openAuthModal}>Authenticate</button>;
}

That's it! When the user clicks that button, the modal will open and they can complete authentication. Once they are authenticated, you can use the useAccount hook to get the logged in user's SCA address.

Want to display a loading state during authentication?
For authentication with redirects in a modal, you may want to add a loading state when users are waiting for authentication to complete. To do this, manage the loading state directly using our hooks, as shown below. In embedded authentication and non-redirect flows, such as passkey authentication, we handle the loading state for you.

import { useAuthModal, useSignerStatus } from "@account-kit/react";
import { useEffect } from "react";
 
const { openAuthModal } = useAuthModal();
const { isAuthenticating } = useSignerStatus();
 
useEffect(() => {
  if (isAuthenticating) {
    openAuthModal();
  }
}, [openAuthModal, isAuthenticating]);

Embedded auth

The body of the Auth Modal is also exported for you to use directly in your application. This is useful if you don't want a modal flow for login and want a standalone page using the card.

import React from "react";
import { AuthCard } from "@account-kit/react";
 
export default function MyLoginPage() {
  return (
    <div className="flex flex-row p-4 bg-white border border-gray-200 rounded-lg">
      <AuthCard />
    </div>
  );
}

That's it! The user can now input their credentials and complete login. Once they are authenticated, you can use the useAccount hook to get the logged in user's SCA address

Customize authentication UI

When rendering the authentication component to your users, it's possible to customize the various sections a user will see as well as the content of the modal.

How does the UI config work?

  • auth property accepts a sections object

  • sections object is an array of arrays representing the various sections in descending order, each section (element in the outer array) separated by a divider in the UI

  • each item within a section is an AuthTypes objects containing configuration parameters for that authentication method.


The following AuthTypes can be passed into sections:

Email

This adds an email login to a section. The shape of this auth type is:

type EmailAuthType = {
  type: "email";
  // hides the continue button
  hideButton?: boolean;
  // changes the button label
  buttonLabel?: string;
  // changes the placeholder text in the input
  placeholder?: string;
};

Passkey

This adds a passkey login method to a section. Passkey login allows users to log in with a passkey they've created else where in your app after logging in, or right after sign-up if you've enabled that setting. The shape of this auth type is:

type PasskeyAuthType = {
  type: "passkey";
};

External wallets

This adds an external wallet login method to a section. This allows users to connect to your app with existing EOAs via browser extension or WalletConnect. The shape of this auth type is:

type ExternalWalletsAuthType = {
  type: "external_wallets";
  // if this is undefined, wallet connect will not be displayed
  walletConnect?: WalletConnectParameters;
};

Social

This adds social authentication methods to a section. Social login authentication allows you to log in and sign up users using an OAuth provider, such as Google Sign-In or Facebook Login. You can also configure custom providers through Auth0. The shape of this auth type is:

type SocialAuthType = {
  type: "social";
  // Specifies the requested OAuth scope
  scope?: string;
  // Specifies additional claims to be included in the authentication token
  claims?: string;
} & (
  | {
      // For using the Auth0 authentication provider
      authProviderId: "auth0";
      // Indicates whether a custom provider is used (default is false)
      isCustomProvider?: false;
      // Auth0-specific connection string
      auth0Connection?: string;
      // URL for the provider's logo
      logoUrl: string;
      // URL for the provider's logo in dark mode (optional, `logoUrl` is used for both light & dark mode if not provided)
      logoUrlDark?: string;
    }
  | {
      // For using a known authentication provider other than Auth0: "google", "facebook", "apple"
      authProviderId: KnownAuthProvider;
      // Indicates whether a custom provider is used (default false)
      isCustomProvider?: false;
      // Auth0 connection should not be specified when using other providers
      auth0Connection?: never;
      // Logo URL is optional for other providers
      logoUrl?: never;
    }
) &
  OauthRedirectConfig;

Example

Here's an example ui configuration which adds 3 sections to the auth modal. The first section contains an email auth, the second section is for passkey login and 2 social auth logins (google and facebook), and the third section is external wallets.

import { AlchemyAccountsUIConfig, createConfig } from "@account-kit/react";
import { sepolia, alchemy } from "@account-kit/infra";
 
const uiConfig: AlchemyAccountsUIConfig = {
  illustrationStyle: "outline",
  auth: {
    sections: [
      [{ type: "email" }],
      [
        { type: "passkey" },
        { type: "social", authProviderId: "google", mode: "popup" },
        { type: "social", authProviderId: "facebook", mode: "popup" },
      ],
      [
        {
          type: "external_wallets",
          walletConnect: { projectId: "your-project-id" },
        },
      ],
    ],
    addPasskeyOnSignup: false,
  },
};
 
export const confg = createConfig(
  {
    transport: alchemy({ apiKey: "your-api-key" }),
    chain: sepolia,
  },
  uiConfig
);

This example would output a modal similar to this image:

Example custom UI config