@futureverse/auth-ui

Futureverse Auth UI

Futureverse Auth UI is a React Theme UI provider for Futureverse Auth React. It offers a set of customizable UI components and theming for seamless integration of FuturePass authentication in your React applications.

Installation

Choose your preferred package manager to install:

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

Features

• Theming: Pre-configured Futureverse theming for quick auth UI setup
• Customizable UI: Fully adaptable to your project's requirements
• Whitelabelling: Customize the auth-ui modal to fit your branding look
• Plug and Play components: Ready-to-use React components for rapid development

Basic Setup

For authClient setup please see refer to @futureverse/auth-react documentation.

'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}>
            {children}
          </AuthUiProvider>
        </FutureverseAuthProvider>
      </FutureverseWagmiProvider>
    </QueryClientProvider>
  );
}

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

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

  return <button onClick={() => openLogin()}>Login</button>;
}

References

Providers

• AuthUiProvider: Main provider for Auth UI
• AuthThemeProvider: Theme provider (used internally by AuthUiProvider)
• Note: AuthThemeProvider is a child of AuthUiProvider

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

/**
 * AuthThemeProvider is used for full custom flow - not needed if using only AuthUiProvider
 */

<AuthThemeProvider themeConfig={...}> //Theme object goes here
  {children}
</AuthThemeProvider>

Hooks

• useAuthUi(): Access login state and controls
• useAuthTheme(): Access theme configuration

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

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

Themes

• 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 and Fonts 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;
  images?: {
    background?: string;
    logo?: string;
  };
} & {
  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;
};

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.
• 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',
  },
};

const customThemeConfig: ThemeConfig = {
  ...DefaultTheme,
  colors: {
    ...DefaultTheme.colors,
    muted: 'rgba(1, 1, 1, 1)',
  },
};

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

• 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