@futureverse/auth-ui

Futureverse Auth UI

A client-side React UI library that provides customizable authentication components and flows for Web3 wallets and Pass custodial authentication. Works with both Futureverse Auth React for standard React applications and @futureverse/next-auth for Next.js applications, enabling seamless integration of both decentralized wallet connections and custodial Pass authentication.

Installation

npm install @futureverse/auth-ui
# or
yarn add @futureverse/auth-ui
# or
pnpm add @futureverse/auth-ui
# or
bun add @futureverse/auth-ui

Peer Dependencies

Make sure to install the required peer dependencies:

npm install wagmi viem @tanstack/react-query
# or
yarn add wagmi viem @tanstack/react-query
# or
pnpm add wagmi viem @tanstack/react-query
# or
bun add wagmi viem @tanstack/react-query

Features

• 🎨 Pre-built Themes - Ready-to-use Futureverse theming
• 🔧 Fully Customizable - Adapt components to match your brand
• 🏷️ White-labeling - Custom logos, colors, and branding
• 🧩 Plug & Play - Drop-in React components for rapid development

Quick Start

Prerequisites: Make sure you have set up your authClient by following the @futureverse/auth-react documentation.

1. Create Wagmi Configuration

// wagmi-config.ts
import { createWagmiConfig } from '@futureverse/wagmi-connectors';
import { mainnet, sepolia } from 'viem/chains';
import { cookieStorage, createStorage } from 'wagmi';
import { authClient } from './auth';

export const wagmiConfig = createWagmiConfig({
  walletConnectProjectId: 'YOUR_WALLETCONNECT_PROJECT_ID',
  xamanAPIKey: 'YOUR_XAMAN_API_KEY', // Optional
  authClient,
  ssr: true, // Set to true for SSR apps
  chains: [mainnet, sepolia], // Add your required chains
  storage: createStorage({
    storage: cookieStorage,
  }),
  metamaskDappMetadata: {
    name: 'Your App Name',
    url: 'http://localhost:3000',
  },
}); 

2. Setup Providers

'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { type ThemeConfig, AuthUiProvider, DefaultTheme } from '@futureverse/auth-ui';
import React from 'react';
import { authClient } from './auth';
import { wagmiConfig } from './wagmi-config';

const queryClient = new QueryClient();

const customThemeConfig: ThemeConfig = {
  ...DefaultTheme,
  defaultAuthOption: 'web3',
};

export default function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthUiProvider 
        themeConfig={customThemeConfig} 
        authClient={authClient}
        wagmiConfig={wagmiConfig}
      >
        {children}
      </AuthUiProvider>
    </QueryClientProvider>
  );
}

3. Use Authentication Hook

import { useAuthUi } from '@futureverse/auth-ui';

export default function LoginButton() {
  const { openLogin, closeLogin, isLoginOpen, currentState } = useAuthUi();

  return <button onClick={() => openLogin()}>{isLoginOpen ? 'Close Login' : 'Open Login'}</button>;
}

API Reference

Providers

AuthUiProvider

The main provider component that wraps your application with Auth UI functionality.

import { AuthUiProvider } from '@futureverse/auth-ui';

<AuthUiProvider 
  themeConfig={themeConfig} 
  authClient={authClient}
  wagmiConfig={wagmiConfig}
  legalLinks={{
    privacyPolicyUrl: 'https://yourcompany.com/privacy-policy',
    termsOfServiceUrl: 'https://yourcompany.com/terms-of-service',
  }}
>
  {children}
</AuthUiProvider>;

Props

Prop	Type	Required	Description
themeConfig	ThemeConfig	Yes	Theme configuration object
authClient	FutureverseAuthClient	Yes	Auth client instance
wagmiConfig	Config	Yes	Wagmi configuration instance
locale	Locale	No	Localization settings
orderedConnectorIds	string[]	No	Custom order for wallet connectors
legalLinks	LegalLinks	No	Company legal links

legalLinks

The legalLinks prop allows you to customize the branding and legal information displayed in authentication flows, particularly in session prompt.

type LegalLinks = {
  privacyPolicyUrl: string;    // URL to privacy policy
  termsOfServiceUrl: string;   // URL to terms of service
};

Example usage:

const legalLinks = {
  privacyPolicyUrl: 'https://yourcompany.com/privacy',
  termsOfServiceUrl: 'https://yourcompany.com/terms',
};

<AuthUiProvider
  themeConfig={themeConfig}
  authClient={authClient}
  wagmiConfig={wagmiConfig}
  legalLinks={legalLinks}
>
  {children}
</AuthUiProvider>

When provided, this information will be displayed in session prompts with text like: "Before connecting, review this app’s privacy policy and terms of service."

AuthThemeProvider

Advanced theme provider for custom authentication flows. Used internally by AuthUiProvider.

import { AuthThemeProvider } from '@futureverse/auth-ui';

<AuthThemeProvider themeConfig={themeConfig}>{children}</AuthThemeProvider>;

Hooks

useAuthUi()

Access authentication modal state and controls.

import { useAuthUi } from '@futureverse/auth-ui';

const {
  isLoginOpen, // Boolean: modal open state
  openLogin, // Function: open the modal
  closeLogin, // Function: close the modal
} = useAuthUi();

useAuthTheme()

Access the current theme configuration.

import { useAuthUi, useAuthTheme } from '@futureverse/auth-ui';

const { isLoginOpen, openLogin, closeLogin } = useAuthUi();
const { themeConfig } = useAuthTheme();

Theming

• DefaultTheme: Delivers the classic Futureverse aesthetic, ready to use out of the box.
• CoreColors: Includes essential colors, such as black, white, and transparent variants for versatile styling.
• Other Typesafe Theme Types: Access additional types like ThemeConfig, AuthOption, Colors, Fonts, BorderRadius for enhanced customization.
• Whitelabeling: Add a modal logo image or a background image to seamlessly integrate the auth UI modal with your personalized brand identity.

import { type ThemeConfig, DefaultTheme, AuthOption, CoreColors } from '@futureverse/auth-ui';

type ThemeConfig = {
  defaultAuthOption?: AuthOption; // 'web3' | 'custodial'
  showCloseButton?: boolean;
  colors: Colors;
  font: Fonts;
  titleFont?: Fonts; // Optional separate title font
  borderRadius: BorderRadius;
  blur?: number; // Blur effect intensity
  images?: {
    background?: string; // Background image URL
    logo?: string; // Logo image URL
  };
  // Visibility controls
  hideWeb3?: boolean;
  hideCustodial?: boolean;
  hideConnectors?: Array<string>;
};

type AuthOption = 'web3' | 'custodial';

type Colors = {
  /** Primary */
  primaryBackground: string;
  primaryForeground: string;
  primaryHover: string;
  primaryActive: string;
  primaryBackgroundDisabled: string;
  primaryForegroundDisabled: string;

  /** Secondary */
  secondaryBackground: string;
  secondaryForeground: string;
  secondaryHover: string;
  secondaryActive: string;
  secondaryBackgroundDisabled: string;
  secondaryForegroundDisabled: string;

  /** Border */
  border: string;
  borderHover: string;
  borderActive: string;
  borderError: string;

  /** Shared Stylings */
  errorForeground: string;
  body: string;
  muted: string;
  surface: string;
  page: string;
};

type Fonts = {
  fontUrl: string;
  fontName: string;
};

type BorderRadius = {
  none: number;
  default: number;
  large: number;
};

Overwrite Theming and Font Examples

• Color Values: All color properties must be specified using RGBA values for consistency and transparency control.
• Font Customization: You can easily integrate custom fonts by providing the font URL and name. By default, title and body fonts will utilize the same font, but you have freedom to set a title font.
• Border Radius: The ability to tweak the border-radius px number values of auth-ui components to your liking.
• Blur: You are able to tweak the blur px value for various components such as Card, Dialog, Dropdown.
• Comprehensive Theming: The theme object allows you to customize various aspects. You can either create a completely custom theme or selectively override specific elements while inheriting the rest from the default theme.

import { type ThemeConfig } from '@futureverse/auth-ui';

const customThemeConfig: ThemeConfig = {
  defaultAuthOption: 'web3',
  colors: {
    // Primary colors
    primaryBackground: 'rgba(255, 255, 255, 0.1)',
    primaryForeground: 'rgba(255, 255, 255, 1)',
    primaryHover: 'rgba(255, 255, 255, 0.2)',
    primaryActive: 'rgba(133, 133, 133, 1)',
    primaryBackgroundDisabled: 'rgba(218, 218, 218, 0.2)',
    primaryForegroundDisabled: 'rgba(165, 163, 164, 1)',

    // Secondary colors
    secondaryBackground: 'rgba(0, 0, 0, 1)',
    secondaryForeground: 'rgba(165, 163, 164, 1)',
    secondaryHover: 'rgba(207, 207, 207, 1)',
    secondaryActive: 'rgba(207, 207, 207, 1)',
    secondaryBackgroundDisabled: 'rgba(218, 218, 218, 0.2)',
    secondaryForegroundDisabled: 'rgba(165, 163, 164, 1)',

    // Border colors
    border: 'rgba(68, 68, 68, 1)',
    borderHover: 'rgba(255, 255, 255, 1)',
    borderActive: 'rgba(255, 255, 255, 1)',
    borderError: 'rgba(171, 21, 57, 1)',

    // Utility colors
    errorForeground: 'rgba(171, 21, 57, 1)',
    body: 'rgba(255, 255, 255, 1)',
    muted: 'rgba(182, 182, 182, 1)',
    surface: 'rgba(0, 0, 0, 0.5)',
    page: 'rgba(24, 24, 24, 1)',
  },
  font: {
    fontUrl: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap',
    fontName: 'Inter',
  },
  borderRadius: {
    none: 0,
    default: 8,
    large: 24,
  },
  blur: 8,
};

const customThemeConfig: ThemeConfig = {
  ...DefaultTheme,
  colors: {
    ...DefaultTheme.colors,
    muted: 'rgba(1, 1, 1, 1)',
  },
  borderRadius: {
    ...DefaultTheme.borderRadius,
    default: 10,
  },
  blur: 8,
};

orderedConnectorIds Prop

You can control the display order of connector options in the Auth UI modal by passing the orderedConnectorIds prop to AuthUiProvider. This prop should be an array of connector IDs (strings). Both Web3 and Custodial connector options will be sorted to match the order specified in this array. Any connectors not listed will appear after the ordered ones, in their default order.

Example:

<AuthUiProvider themeConfig={customThemeConfig} authClient={authClient} orderedConnectorIds={['metaMaskSDK', 'xaman', 'futureverseCustodialGoogle', 'futureverseCustodialFacebook']} />

• Connectors are displayed in the order specified
• Unlisted connectors appear after ordered ones in their default order
• Works for both Web3 and Custodial authentication options

Components

Futureverse Auth UI provides a comprehensive set of components to build your authentication interface. All components accept standard React props, including style and className for custom styling.

Base Components

• Button: Customizable action button
• Card: Container for grouped content
• Dialog: Modal dialog for important information
• Icon / IconFactory: Render and manage icons
• Image: Optimized image display
• Typography: Text styling component
• Modal: Customizable modal overlay
• Divider: Visual separator for content sections
• FormattedMessage: Render translated text

Plug 'n' Play Components

• Avatar: User profile avatar UI with fallback customization
• ProfileAuthButton: Profile authentication UI
• CustodialAuthButton / CustodialAuthOptions: Custodial authentication UI
• Web3AuthButton / Web3AuthOptions: Web3 authentication UI
• FuturePassAuthOptions: FuturePass-specific auth options
• LoaderAnimation: Loading indicator for async operations
• Input / OTPInput: Text and OTP input fields
• Dropdown: Selectable options in a dropdown format
• Checkbox: Toggleable tick checkbox