Customizing authentication methods

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

In this guide, we'll go over all of the customization options for the auth modal.

Customizing the authentication methods

The auth modal supports a number of different authentication methods that can be enabled or disabled. Before we dive into how to do this and which methods are available, let's go over the configuration.

The UI config's auth property accepts a sections object. This object is an array of arrays which represents the various sections in descending order. Each section (element in the outer array) is separated by a divider. The items within a section are called AuthTypes and these objects contain configuration parameters for that authentication method.

Auth Types

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 login 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;
};

Example

Here's an example configuration which adds 3 sections to the auth modal. The first section contains an email auth, the second section is for passkey login, and the third section is external wallets.

import { createConfig } from "@account-kit/react";
import { sepolia } from "@account-kit/infra";
 
export const confg = createConfig(
  {
    apiKey: "YOUR_API_KEY",
    chain: sepolia,
  },
  {
    auth: {
      // This prompts the user to add a passkey after the sign-up with email the first time
      addPasskeyOnSignup: true,
      sections: [
        [{ type: "email" }],
        [{ type: "passkey" }],
        [{ type: "external_wallets" }],
      ],
    },
  }
);

Custom headers

The auth modal, by default, shows a Sign in text header. This header is fully cusomizable by you, allowing you to change the text or add an icon. To customize the header text, you can override either of the header or hideSignInText options of the auth config when calling createConfig.

Changing the header text

In this example, we hide the default header text and replace it with our own.

import { createConfig } from "@account-kit/react";
import { sepolia } from "@account-kit/infra";
 
export const confg = createConfig(
  {
    apiKey: "YOUR_API_KEY",
    chain: sepolia,
  },
  {
    auth: {
      header: "Sign in with your account", 
      hideSignInText: true, 
    },
  }
);

Adding an icon

In this example, we leave the Sign in text in the modal and add an icon above it.

import { createConfig } from "@account-kit/react";
import { sepolia } from "@account-kit/infra";
 
export const confg = createConfig(
  {
    apiKey: "YOUR_API_KEY",
    chain: sepolia,
  },
  {
    auth: {
      header: <img src="img.src" />, 
    },
  }
);