Custom theme | Alchemy Docs

When using React components in your app, you can customize both 1) overall theme and 2) authentication components.

Most theme customizations are passed through using withAccountKitUi, the Account Kit Tailwind plugin, in your tailwind.config.js file.

The easiest way to configure your UI components, is using the Demo App.

Colors

The Account Kit Theme object passed to withAccountKitUi supports an overiddable colors object which accepts a set of color values. Each color is a key-value pair where the key is the name of the color and the value is an object containing the light and dark mode value to use.

Border colors

active - the color of the border when the input is focused
static - the color of the border when the input is not focused
critical - the color of the border when the input is in an error state

Button colors

These colors affect the background of buttons

btn-primary - the color of the primary button
btn-secondary - the color of the secondary button
btn-auth - the color of the authentication button

Foreground colors

These colors primarily affect the text color of the components

fg-primary - the color of the primary text
fg-secondary - the color of the secondary text
fg-tertiary - the color of the tertiary text
fg-invert - the color of the inverted text
fg-disabled - the color of the disabled text
fg-accent-brand - your brand color
fg-critical - the color of the critical text

Surface colors

These colors affect the background of various components (eg. modal, inputs, etc)

bg-surface-default - the default background color
bg-surface-subtle - a subtle background color
bg-surface-inset - the background color of inset components
bg-surface-critical - the background color of critical components
bg-surface-error - the background color of error components
bg-surface-success - the background color of success components
bg-surface-warning - the background color of warning components

Example

import { const withAccountKitUi: (config: Partial<Config>, themeOverride?: AccountKitThemeOverride) => ConfigA utility function for augmenting an existing tailwind config with the account kit ui components
withAccountKitUi, const createColorSet: (light: string, dark: string) => ColorVariantRecordCreates a color object to be used within account kit utilities, components, and themes
createColorSet } from "@account-kit/react/tailwind";

export const const tailwindConfig: UserConfig
tailwindConfig = function withAccountKitUi(config: Partial<Config>, themeOverride?: AccountKitThemeOverride): ConfigA utility function for augmenting an existing tailwind config with the account kit ui components
withAccountKitUi(
  {
    content?: ContentFile[] | {
    relative?: boolean;
    files: ContentFile[];
} | undefined
content: [],
    // your tailwind config
  },
  {
    colors?: {
    active?: {
        dark?: string | undefined;
        light?: string | undefined;
    } | undefined;
    static?: {
        dark?: string | undefined;
        light?: string | undefined;
    } | undefined;
    critical?: {
        dark?: string | undefined;
        light?: string | undefined;
    } | undefined;
    ... 17 more ...;
    "bg-surface-error"?: {
        dark?: string | undefined;
        light?: string | undefined;
    } | undefined;
} | undefined
colors: {
      active?: {
    dark?: string | undefined;
    light?: string | undefined;
} | undefined
active: function createColorSet(light: string, dark: string): ColorVariantRecordCreates a color object to be used within account kit utilities, components, and themes
createColorSet("#94A3B8", "#94A3B8"),
    },
  },
);

Borders

Similar to colors, the Account Theme object passed to withAccountKitUi supports an overiddable borderRadius field to customize the border radius size. The default value is sm which is an 8px border radius.

import { const withAccountKitUi: (config: Partial<Config>, themeOverride?: AccountKitThemeOverride) => ConfigA utility function for augmenting an existing tailwind config with the account kit ui components
withAccountKitUi } from "@account-kit/react/tailwind";

export const const tailwindConfig: UserConfig
tailwindConfig = function withAccountKitUi(config: Partial<Config>, themeOverride?: AccountKitThemeOverride): ConfigA utility function for augmenting an existing tailwind config with the account kit ui components
withAccountKitUi(
  {
    content?: ContentFile[] | {
    relative?: boolean;
    files: ContentFile[];
} | undefined
content: [],
    // your tailwind config
  },
  {
    borderRadius?: "none" | "xs" | "sm" | "md" | "lg" | undefined
borderRadius: "md",
  },
);

The available options are:

none (0px)
xs (4px)
sm (8px)
md (16px)
lg (24px)

Illustration styles

Unlike colors and border radius, illustration styles are not passed through the Tailwind plugin.

Customize the illustration style of various icons used in the components by passing one of the enum values to illustrationStyle in your uiConfig when you call createConfig.

import { const createConfig: (props: CreateConfigProps, ui?: AlchemyAccountsUIConfig) => AlchemyAccountsConfigWithUIWraps the createConfig that is exported from @aa-sdk/core to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).
createConfig } from "@account-kit/react";
import { const sepolia: Chain
sepolia, function alchemy(config: AlchemyTransportConfig): AlchemyTransportCreates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy } from "@account-kit/infra";

const const config: AlchemyAccountsConfigWithUI
config = function createConfig(props: CreateConfigProps, ui?: AlchemyAccountsUIConfig): AlchemyAccountsConfigWithUIWraps the createConfig that is exported from @aa-sdk/core to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).
createConfig(
  {
    transport: AlchemyTransport
transport: function alchemy(config: AlchemyTransportConfig): AlchemyTransportCreates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy({ apiKey: string
apiKey: "YOUR_KEY" }),
    chain: Chain
chain: const sepolia: Chain
sepolia,
  },
  {
    // ... other ui config options
    illustrationStyle?: "outline" | "linear" | "filled" | "flat" | undefined
illustrationStyle: "outline",
  },
);

Custom authentication component

The auth modal, by default, shows a Sign in text header. This header is fully cusomizable, allowing you to change the text or add an icon.

Customize header text

To customize the header text, you can override the header or hideSignInText options of the auth config when calling createConfig. In this example, we hide the default header text and replace it with our own.

import { const createConfig: (props: CreateConfigProps, ui?: AlchemyAccountsUIConfig) => AlchemyAccountsConfigWithUIWraps the createConfig that is exported from @aa-sdk/core to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).
createConfig } from "@account-kit/react";
import { const sepolia: Chain
sepolia, function alchemy(config: AlchemyTransportConfig): AlchemyTransportCreates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy } from "@account-kit/infra";

export const const confg: AlchemyAccountsConfigWithUI
confg = function createConfig(props: CreateConfigProps, ui?: AlchemyAccountsUIConfig): AlchemyAccountsConfigWithUIWraps the createConfig that is exported from @aa-sdk/core to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).
createConfig(
  {
    transport: AlchemyTransport
transport: function alchemy(config: AlchemyTransportConfig): AlchemyTransportCreates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy({ apiKey: string
apiKey: "YOUR_KEY" }),
    chain: Chain
chain: const sepolia: Chain
sepolia,
  },
  {
    auth?: {
    addPasskeyOnSignup?: boolean;
    header?: React.ReactNode;
    hideError?: boolean;
    onAuthSuccess?: () => void;
    sections: AuthType[][];
    hideSignInText?: boolean;
} | undefined
auth: {
      header?: React.ReactNode
header: "Sign in with your account",
      hideSignInText?: boolean | undefinedWhether to show the "Sign in" header text in the first auth step
hideSignInText: true,
    },
  },
);

Adding an icon

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

import { const createConfig: (props: CreateConfigProps, ui?: AlchemyAccountsUIConfig) => AlchemyAccountsConfigWithUIWraps the createConfig that is exported from @aa-sdk/core to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).
createConfig } from "@account-kit/react";
import { const sepolia: Chain
sepolia, function alchemy(config: AlchemyTransportConfig): AlchemyTransportCreates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy } from "@account-kit/infra";

export const const confg: AlchemyAccountsConfigWithUI
confg = function createConfig(props: CreateConfigProps, ui?: AlchemyAccountsUIConfig): AlchemyAccountsConfigWithUIWraps the createConfig that is exported from @aa-sdk/core to allow passing an additional argument, the configuration object for the Auth Components UI (the modal and AuthCard).
createConfig(
  {
    transport: AlchemyTransport
transport: function alchemy(config: AlchemyTransportConfig): AlchemyTransportCreates an Alchemy transport with the specified configuration options. When sending all traffic to Alchemy, you must pass in one of rpcUrl, apiKey, or jwt. If you want to send Bundler and Paymaster traffic to Alchemy and Node traffic to a different RPC, you must pass in alchemyConnection and nodeRpcUrl.
alchemy({ apiKey: string
apiKey: "YOUR_KEY" }),
    chain: Chain
chain: const sepolia: Chain
sepolia,
  },
  {
    auth?: {
    addPasskeyOnSignup?: boolean;
    header?: React.ReactNode;
    hideError?: boolean;
    onAuthSuccess?: () => void;
    sections: AuthType[][];
    hideSignInText?: boolean;
} | undefined
auth: {
      header?: React.ReactNode
header: <React.JSX.IntrinsicElements.img: React.DetailedHTMLProps<React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>
img React.ImgHTMLAttributes<HTMLImageElement>.src?: string | undefined
src="img.src" />,
    },
  },
);