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
yarn add @futureverse/auth-ui
pnpm add @futureverse/auth-ui
bun add @futureverse/auth-ui
Peer Dependencies
Make sure to install the required peer dependencies:
npm install wagmi viem @tanstack/react-query
yarn add wagmi viem @tanstack/react-query
pnpm add wagmi viem @tanstack/react-query
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
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',
authClient,
ssr: true,
chains: [mainnet, sepolia],
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
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;
termsOfServiceUrl: string;
};
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,
openLogin,
closeLogin,
} = 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;
showCloseButton?: boolean;
colors: Colors;
font: Fonts;
titleFont?: Fonts;
borderRadius: BorderRadius;
blur?: number;
images?: {
background?: string;
logo?: string;
};
hideWeb3?: boolean;
hideCustodial?: boolean;
hideConnectors?: Array<string>;
};
type AuthOption = 'web3' | 'custodial';
type Colors = {
primaryBackground: string;
primaryForeground: string;
primaryHover: string;
primaryActive: string;
primaryBackgroundDisabled: string;
primaryForegroundDisabled: string;
secondaryBackground: string;
secondaryForeground: string;
secondaryHover: string;
secondaryActive: string;
secondaryBackgroundDisabled: string;
secondaryForegroundDisabled: string;
border: string;
borderHover: string;
borderActive: string;
borderError: string;
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: {
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)',
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: 'rgba(68, 68, 68, 1)',
borderHover: 'rgba(255, 255, 255, 1)',
borderActive: 'rgba(255, 255, 255, 1)',
borderError: 'rgba(171, 21, 57, 1)',
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