@futureverse/auth-ui
v0.5.0
Published
Futureverse Auth UI is a React Theme UI provider for [Futureverse Auth React](https://www.npmjs.com/package/@futureverse/auth-react). It offers a set of customizable UI components and theming for seamless integration of FuturePass authentication in your R
Downloads
2,870
Maintainers
Keywords
Readme
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';
export type ThemeConfig = {
defaultAuthOption?: AuthOption;
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
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