Installation

Install the widget library and its peer dependencies, then configure providers based on your integration mode. Both Passkey Signing and Metadata Mode start with the same base install.

Install Packages

npm install @relayerfi/widget-kit-react wagmi viem @tanstack/react-query framer-motion

pnpm add @relayerfi/widget-kit-react wagmi viem @tanstack/react-query framer-motion

yarn add @relayerfi/widget-kit-react wagmi viem @tanstack/react-query framer-motion

@relayerfi/action-kit and @relayerfi/widget-kit-core are peer packages bundled internally — you do not install them separately.

Choose Your Integration Mode

Passkey Signing
Metadata Mode

Passkey Signing is for integrators using Relayer’s managed wallet stack. Each integrator gets a dedicated wallet workspace with passkey-based signing.

In addition to the base packages, Passkey Signing integrators should be aware that:

The widget handles passkey prompts internally — no additional signing SDK install is needed in your frontend
Your users will see a biometric prompt (Face ID, fingerprint, security key) when signing transactions
Wallet creation and passkey registration are handled through the Relayer API and dashboard

Proceed to the wagmi configuration below — the Widget component manages the signing flow automatically.

Configure Wagmi

Create a wagmi config file. This example uses mainnet with the browser injected connector:

src/wagmi.ts

import { createConfig, http } from 'wagmi';
import { mainnet } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';

export const wagmiConfig = createConfig({
  chains: [mainnet],
  connectors: [injected()],
  transports: {
    [mainnet.id]: http(),
  },
});

Add more chains and connectors (WalletConnect, Coinbase Wallet) as needed. See the wagmi docs for the full configuration API.

Wrap Your App

wagmi v2 requires WagmiProvider and QueryClientProvider at the root of your component tree.

Next.js App Router
React (Vite / CRA)

Create a client component for providers:

src/app/providers.tsx

'use client';

import { WagmiProvider } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { wagmiConfig } from '@/wagmi';

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        {children}
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Then use <Providers> in your root layout:

src/app/layout.tsx

import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Wrap your app entry point:

src/main.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { WagmiProvider } from 'wagmi';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { wagmiConfig } from './wagmi';
import App from './App';

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById('root')!).render(
  <WagmiProvider config={wagmiConfig}>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </WagmiProvider>,
);

Import CSS

Widget components require the bundled stylesheet. Import it once in your entry point:

import '@relayerfi/widget-kit-react/index.css';

For Next.js, add this import to app/layout.tsx or pages/_app.tsx.

Verify Installation

Once providers are configured and the CSS is imported, you can render a <Widget> component. See the Integration Guide for a full working example.

Widget Kit

Install Packages

Choose Your Integration Mode

Configure Wagmi

Wrap Your App

Import CSS

Verify Installation

Next Steps

Integration Guide

Widget Kit Overview

​Install Packages

​Choose Your Integration Mode

​Configure Wagmi

​Wrap Your App

​Import CSS

​Verify Installation

​Next Steps

Integration Guide

Widget Kit Overview

Install Packages

Choose Your Integration Mode

Configure Wagmi

Wrap Your App

Import CSS

Verify Installation

Next Steps