> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayer.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install @relayerfi/widget-kit-react and configure providers for Passkey Signing or Metadata Mode integration

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

<CodeGroup>
  ```bash npm theme={null}
  npm install @relayerfi/widget-kit-react wagmi viem @tanstack/react-query framer-motion
  ```

  ```bash pnpm theme={null}
  pnpm add @relayerfi/widget-kit-react wagmi viem @tanstack/react-query framer-motion
  ```

  ```bash yarn theme={null}
  yarn add @relayerfi/widget-kit-react wagmi viem @tanstack/react-query framer-motion
  ```
</CodeGroup>

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

## Choose Your Integration Mode

<Tabs>
  <Tab title="Passkey Signing">
    <Info>
      Passkey Signing is for integrators using Relayer's managed wallet stack. Each integrator gets a dedicated wallet workspace with passkey-based signing.
    </Info>

    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.
  </Tab>

  <Tab title="Metadata Mode">
    <Info>
      Metadata Mode is for integrators who bring their own wallet stack (MPC, HSM, MetaMask, WalletConnect, or any EVM-compatible signer).
    </Info>

    No additional packages are needed beyond the base install. In Metadata Mode:

    * The widget requests routing and calldata from the Relayer API
    * Your application receives the transaction metadata
    * You build, sign, and broadcast using your own wallet stack

    The wagmi configuration below is still recommended for chain management and provider connectivity, but transaction signing is handled by your infrastructure.
  </Tab>
</Tabs>

## Configure Wagmi

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

```typescript src/wagmi.ts theme={null}
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](https://wagmi.sh/react/config) for the full configuration API.

## Wrap Your App

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

<Tabs>
  <Tab title="Next.js App Router">
    Create a client component for providers:

    ```typescript src/app/providers.tsx theme={null}
    '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:

    ```typescript src/app/layout.tsx theme={null}
    import { Providers } from './providers';

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

  <Tab title="React (Vite / CRA)">
    Wrap your app entry point:

    ```typescript src/main.tsx theme={null}
    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>,
    );
    ```
  </Tab>
</Tabs>

## Import CSS

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

```typescript theme={null}
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](/widget/integration) for a full working example.

## Next Steps

<CardGroup cols={2}>
  <Card title="Integration Guide" icon="plug" href="/widget/integration">
    Embed and theme your first widget.
  </Card>

  <Card title="Widget Kit Overview" icon="layer-group" href="/widget/overview">
    Understand the package ecosystem.
  </Card>
</CardGroup>