Quick start

Add the PartyLayer wallet picker and account menu to your React app. One installation includes the SDK and reviewed wallet runtimes. No wallet-specific imports or stylesheet import are required.

Use React 18+ and a supported Node LTS version that meets your framework requirements. To complete a real connection, users need a wallet account or extension on your selected network.

Start a new app

The CLI creates your project and installs its dependencies:

npm create partylayer-app@latest my-dapp -- --template react-vite --pm npm
cd my-dapp
npm run dev

Use --template next-ssr for Next.js App Router. The CLI guide lists all six templates. Generated React apps already use the PartyLayer button and attribution. For an existing app, follow the steps below.

Step 1: Install

npm install @partylayer/react @tanstack/react-query

You do not need a separate SDK, core or wallet package installation. TanStack Query is a required peer. Its QueryClientProvider is needed for optional @partylayer/react/query data hooks; the base connect UI works without that provider.

Step 2: Mount the kit

// src/main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { PartyLayerKit } from '@partylayer/react';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <PartyLayerKit network="devnet" appName="My dApp">
      <App />
    </PartyLayerKit>
  </StrictMode>,
);

In Next.js, mount the provider in your server-rendered root layout:

// app/layout.tsx — keep this a Server Component
import type { ReactNode } from 'react';
import { Providers } from './providers';

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

Use one kit at your application boundary. It owns discovery, client cleanup, theme and session context. Keep walletConnect, bron and additionalAdapters objects stable outside render or with useMemo; changes recreate the client.

Step 3: Add ConnectButton

Use src/App.tsx in Vite or app/page.tsx in Next.js:

'use client';

import { ConnectButton } from '@partylayer/react';

export default function Home() {
  return (
    <main>
      <h1>My Canton dApp</h1>
      <ConnectButton />
    </main>
  );
}

Users choose a wallet and approve its connection. The connected button opens the account menu. The modal shows Powered by PartyLayer by default. Hosted login and extension installation remain wallet prerequisites.

Read the connected account

import { useAccount } from '@partylayer/react';

export function Account() {
  const { isConnected, status, party, networkId } = useAccount();
  if (!isConnected) return <p>Wallet: {status}</p>;
  return <p>{party} · {networkId}</p>;
}

Render this inside the kit. A wallet session is not application authentication; use the authentication guide for server-verified sign-in. For optional data hooks, wrap the kit in QueryClientProvider. In a Next.js client provider, create its stable client with useState(() => new QueryClient()) rather than sharing it across server requests. See data hooks.

Configure wallets

• Network: set network to devnet, testnet or mainnet. The catalog follows network support.
• Vala: set network="devnet" channel="beta".
• Send: Mainnet-only in the catalog; it is absent on Devnet.
• WalletConnect: supply your own project ID through walletConnect.
• Bron: supply your OAuth/API configuration through bron.
• Custom integrations: additionalAdapters extends the catalog; adapters replaces it.
• Appearance: use theme="auto" locale="en"; 14 UI languages, automatic Arabic RTL and explicit direction overrides are supported.

const walletConnect = { projectId: 'YOUR_PROJECT_ID' };

<PartyLayerKit network="devnet" appName="My dApp" walletConnect={walletConnect}>
  <ConnectButton />
</PartyLayerKit>

Runtimes ship with the kit and load as needed. A listing or capability declaration is not proof of completed live testing. See wallet capabilities and the acceptance evidence.

Verify the connection

1. Open Connect Wallet and check the list against your network and channel.
2. Select a wallet from the button flow; complete login, installation and approval if needed.
3. Confirm useAccount() reports the party and actual wallet network.
4. Disconnect and confirm the account clears. Test reload/restoration separately; a cached hint alone is not a live connection.

Troubleshooting

• Missing wallet: check network/channel, WalletConnect/Bron settings and whether adapters replaced defaults.
• Empty picker: check registry/discovery errors, filters and custom adapter configuration.
• Popup blocked: start from a user click; use the default button to preserve the supported popup flow.
• Signing rejected: check session capabilities, actual network and wallet authentication. Inspect the vendor error.
• Signature verification failed: verify exact challenge bytes/encoding, nonce, origin and independently authorized key. There is no universal vendor algorithm.
• Old native session: caches without an official provider hint need one reconnect. Live party/network checks still apply.
• Next.js hydration: keep the kit in a client boundary. SSR cookie state is a UI hint; protect server content with backend authentication.

Next steps

• Kit configuration and ConnectButton.
• Authentication, transaction lifecycle and wallet balances.
• Token transfers and their wallet-specific command requirements.
• Protocol ownership and migration for existing apps.
• Framework-independent SDK for a custom application stack.