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.
npm install @futureverse/auth-ui
# or
yarn add @futureverse/auth-ui
# or
pnpm add @futureverse/auth-ui
# or
bun add @futureverse/auth-ui
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
- 🎨 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
Prerequisites: Make sure you have set up your
authClient
by following the @futureverse/auth-react documentation.
// 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',
},
});
'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>
);
}
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>;
}
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>;
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 |
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."
Advanced theme provider for custom authentication flows. Used internally by AuthUiProvider
.
import { AuthThemeProvider } from '@futureverse/auth-ui';
<AuthThemeProvider themeConfig={themeConfig}>{children}</AuthThemeProvider>;
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();
Access the current theme configuration.
import { useAuthUi, useAuthTheme } from '@futureverse/auth-ui';
const { isLoginOpen, openLogin, closeLogin } = useAuthUi();
const { themeConfig } = useAuthTheme();
- 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;
};
- 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,
};
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
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