UI customization

Overview

The Embedded Wallet Kit provides a set of customizable UI components that you can use to enhance the user experience in your React application. These components open up in a popup modal and can be customized to match your application’s design. The UI components show up automatically when you call certain "handle" functions from the useTurnkey hook, such as handleLogin, handleSignMessage, or handleImport. These functions will open a modal with the appropriate UI for the action. All styles are provided in the @turnkey/react-wallet-kit/styles.css file. You must import this file in your main application file (e.g., app/layout.tsx in Next.js) to ensure the styles are applied correctly.

import "@turnkey/react-wallet-kit/styles.css";

For Tailwind CSS V3 users:Please refer to the Tailwind V3 error in the troubleshooting section for specific instructions on how to import the styles correctly.You can continue with the guide as normal if you are using Tailwind CSS V4 or not using Tailwind CSS at all.

Customizing the UI components

You can customize the look and feel of the modals by configuring the ui object in the TurnkeyProvider’s config. This allows you to toggle light or dark mode, set custom colors, and more. You can see the full list of available options in the SDK Reference or by inspecting the TurnkeyProviderConfig interface.

import {
  TurnkeyProvider,
  TurnkeyProviderConfig,
} from "@turnkey/react-wallet-kit";
import "@turnkey/react-wallet-kit/styles.css";

function App() {
  const turnkeyConfig: TurnkeyProviderConfig = {
    //... your existing configuration
    ui: {
      darkMode: true, // Set to true if you want the UI to be in dark mode. You can attach a toggle to this value.
      colors: {
        // Customize the colors for light and dark modes
        light: {
          primary: "#2ed962", // Greenish color for light mode
        },
        dark: {
          primary: "#da14c3", // Pinkish color for dark mode
        },
      },
      borderRadius: "20px", // Set the border radius for the UI components
      backgroundBlur: "10px", // Set the background blur for the UI components
    },
  };

  return <TurnkeyProvider config={turnkeyConfig}>{children}</TurnkeyProvider>;
}

Here’s how the UI components will look with the above configuration:

Custom UI with pink primary color and dark mode

This applies to all UI components, not just the authentication modal.

Fonts

Turnkey’s modals are rendered inside the body element of your application by default. That means that any fonts that are applied to the body will also be applied to the modals. You can use any font you like, including custom fonts, by applying them to the body element in your CSS.

body {
  font-family: "Your Custom Font", sans-serif;
}

Rendering modals elsewhere

You can force the modals to render as a child to the TurnkeyProvider by setting the renderModalInProvider attribute to true in the TurnkeyProvider’s config. This is useful if you want to render the modals in a specific part of your application, such as a dedicated modal container. This may cause the modals to be distorted in certain cases, so use this option with caution.

import {
  TurnkeyProvider,
  TurnkeyProviderConfig,
} from "@turnkey/react-wallet-kit";
import "@turnkey/react-wallet-kit/styles.css";

function App() {
  const turnkeyConfig: TurnkeyProviderConfig = {
    //... your existing configuration
    ui: {
      //... your existing UI configuration

      renderModalInProvider: true, // Set to true to render modals as a child of the TurnkeyProvider
    },
  };

  return <TurnkeyProvider config={turnkeyConfig}>{children}</TurnkeyProvider>;
}

Making your own modals

You can also use the useModal hook to manually push and pop modals, close modals, or listen to the modal stack. This allows you to manually control the modal experience or create custom modals that fit your application’s design. Your modals can have multiple pages, and you can navigate between them using the pushPage and popPage functions.

import { useModal } from "@turnkey/react-wallet-kit";

function CustomModalButton() {
  const { pushPage, popPage, modalStack } = useModal();

  const openCustomModal = () => {
    pushPage({
      key: "Custom Modal 1",
      content: (
        <div className="flex flex-col items-center justify-center w-72 h-48 mt-8 text-center">
          <p>This is a custom modal.</p>
          <button
            onClick={() =>
              pushPage({
                key: "Custom Modal 2",
                content: (
                  <div className="flex flex-col items-center justify-center w-64 h-32 mt-8 text-center">
                    <p>This is another custom modal.</p>
                  </div>
                ),
              })
            }
          >
            Open Page 2
          </button>
        </div>
      ),
    });
  };

  return <button onClick={openCustomModal}>Open Custom Modal</button>;
}

Your custom modal will inherit the styles and customization options you set in the TurnkeyProvider. Transition effects and a title bar with controls (like close and back buttons) will also be automatically applied. Here’s how it will look:

Next steps

Now that you know how to customize the UI components in your React application, check out the Sub-Organization Customization guide to learn how to customize the sub-orgs that are created for your users. This includes automatically creating wallets, having multiple authentication methods, default usernames, and more.

Overview

Embedded Wallets

Company Wallets

Key Management

Cookbooks

UI customization

Overview

Customizing the UI components

Fonts

Rendering modals elsewhere

Making your own modals

Next steps

​Overview

​Customizing the UI components

​Fonts

​Rendering modals elsewhere

​Making your own modals

​Next steps

Overview

Customizing the UI components

Fonts

Rendering modals elsewhere

Making your own modals

Next steps