@futureverse/auth-ui

Futureverse Auth UI

A React UI library that provides customizable authentication components and theming for Futureverse Auth React. Build beautiful authentication flows with FuturePass integration.

Installation

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

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. Setup Providers

'use client';

import { FutureverseAuthProvider, FutureverseWagmiProvider } from '@futureverse/auth-react';
import { QueryClientProvider } from '@tanstack/react-query';
import { type ThemeConfig, AuthUiProvider, DefaultTheme } from '@futureverse/auth-ui';
import React from 'react';
import { State } from 'wagmi';
import { authClient, getWagmiConfig, queryClient } from './config';

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

export default function Providers({ children, initialWagmiState }: { children: React.ReactNode; initialWagmiState?: State }) {
  return (
    <QueryClientProvider client={queryClient}>
      <FutureverseWagmiProvider getWagmiConfig={getWagmiConfig} initialState={initialWagmiState}>
        <FutureverseAuthProvider authClient={authClient}>
          <AuthUiProvider 
            themeConfig={customThemeConfig} 
            authClient={authClient}
            legalLinks={{
              privacyPolicyUrl: 'https://yourcompany.com/privacy-policy',
              termsOfServiceUrl: 'https://yourcompany.com/terms-of-service',
            }}
          >
            {children}
          </AuthUiProvider>
        </FutureverseAuthProvider>
      </FutureverseWagmiProvider>
    </QueryClientProvider>
  );
}

2. 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}
  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
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}
  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