From e6200c6a2635086551ccd16dc4d483fb95f1d728 Mon Sep 17 00:00:00 2001 From: Bartek Date: Fri, 31 Jul 2026 12:43:31 +0200 Subject: [PATCH] feat: update docs for wallet-react-ui 0.1.0 release --- docs/pages/wallets/auth/wallet-ui-kit.mdx | 145 ------------------ .../auth/wallet-ui-kit/coming-soon.mdx | 11 ++ .../auth/wallet-ui-kit/connect-wallet.mdx | 89 +++++++++++ .../auth/wallet-ui-kit/getting-started.mdx | 42 +++++ .../auth/wallet-ui-kit/installation.mdx | 70 +++++++++ docs/pages/wallets/index.mdx | 4 +- docs/pages/wallets/quickstart.mdx | 4 +- .../wallets/wallet-api/batch-transactions.mdx | 2 +- vocs.config.tsx | 20 ++- 9 files changed, 236 insertions(+), 151 deletions(-) delete mode 100644 docs/pages/wallets/auth/wallet-ui-kit.mdx create mode 100644 docs/pages/wallets/auth/wallet-ui-kit/coming-soon.mdx create mode 100644 docs/pages/wallets/auth/wallet-ui-kit/connect-wallet.mdx create mode 100644 docs/pages/wallets/auth/wallet-ui-kit/getting-started.mdx create mode 100644 docs/pages/wallets/auth/wallet-ui-kit/installation.mdx diff --git a/docs/pages/wallets/auth/wallet-ui-kit.mdx b/docs/pages/wallets/auth/wallet-ui-kit.mdx deleted file mode 100644 index c6d69cd..0000000 --- a/docs/pages/wallets/auth/wallet-ui-kit.mdx +++ /dev/null @@ -1,145 +0,0 @@ -# Wallet UI Kit - -The Wallet UI Kit gives you prebuilt React UI for ZeroDev Wallet. Use it when you want to get started faster with a ready-made login flow instead of building every authentication screen yourself. - -The kit uses a Wagmi-compatible ZeroDev connector, so after the user signs in you can use standard Wagmi hooks such as `useAccount`, `useSignMessage`, and `useSendTransaction`. - -The current kit covers login. More wallet UI components are coming, including prebuilt confirmation screens, onramps, asset management and portfolio views, transaction history, and chain-abstracted balances. - -For a fully custom UI, use the hook-based authentication pages instead: [Passkeys](/wallets/auth/passkeys), [Email OTP](/wallets/auth/email-otp), [Magic Link](/wallets/auth/magic-link), or [Google OAuth](/wallets/auth/google-oauth). If you want to customize the UI Kit flow itself, use the kit's `useAuth` hook from `@zerodev/wallet-react-ui` to read and drive the auth state. - -## Before you start - -In the [ZeroDev Dashboard](https://dashboard.zerodev.app/), make sure your project has: - -- The app origin added to the project's ACL allowlist, such as `http://localhost:3000` for local development. -- The auth methods you plan to show in the UI Kit configured for the project. -- At least one enabled network. - -This guide uses Arbitrum Sepolia and email OTP. Replace the chain, chain RPC URL, and enabled auth methods for your app. - -## Install packages - -:::code-group - -```bash [npm] -npm i @zerodev/wallet-react-ui @zerodev/react-ui @zerodev/wallet-core @zerodev/wallet-react wagmi viem @wagmi/core @tanstack/react-query zustand -``` - -```bash [yarn] -yarn add @zerodev/wallet-react-ui @zerodev/react-ui @zerodev/wallet-core @zerodev/wallet-react wagmi viem @wagmi/core @tanstack/react-query zustand -``` - -```bash [pnpm] -pnpm add @zerodev/wallet-react-ui @zerodev/react-ui @zerodev/wallet-core @zerodev/wallet-react wagmi viem @wagmi/core @tanstack/react-query zustand -``` - -```bash [bun] -bun add @zerodev/wallet-react-ui @zerodev/react-ui @zerodev/wallet-core @zerodev/wallet-react wagmi viem @wagmi/core @tanstack/react-query zustand -``` - -::: - -## Configure Wagmi - -Import `zeroDevWallet` from `@zerodev/wallet-react-ui`. This connector wraps the base ZeroDev Wallet connector and controls the kit's auth UI state. - -```tsx -import { zeroDevWallet } from '@zerodev/wallet-react-ui' -import { createConfig, http } from 'wagmi' -import { arbitrumSepolia } from 'wagmi/chains' - -export const config = createConfig({ - chains: [arbitrumSepolia], - connectors: [ - zeroDevWallet({ - projectId: '', - chains: [arbitrumSepolia], - mode: '7702', - config: { - auth: { - enabledMethods: ['email', 'google', 'passkey'], - emailAuthMethod: 'otp', - }, - }, - }), - ], - transports: { - [arbitrumSepolia.id]: http('https://sepolia-rollup.arbitrum.io/rpc'), - }, -}) -``` - -Only include auth methods that are enabled for your project. This example uses OTP for email authentication; use the hook-based [Magic Link](/wallets/auth/magic-link) guide if you want to build a magic-link flow yourself. - -## Add providers and styles - -Import the kit stylesheet once at your app entry, then wrap your app with Wagmi and TanStack Query providers. If your app has broad global element styles, scope them to your own app shell so they don't override the kit. - -```tsx -import { QueryClient, QueryClientProvider } from '@tanstack/react-query' -import '@zerodev/wallet-react-ui/styles.css' -import { WagmiProvider } from 'wagmi' -import { config } from './wagmi' - -const queryClient = new QueryClient() - - - - {/* your app */} - - -``` - -## Render the login flow - -Find the ZeroDev connector by its `id`, call Wagmi's `connect` to start login, and render `` in the same provider tree — it displays the active auth screen while the connector waits for the user to finish authentication. - -```tsx -import { AuthFlow } from '@zerodev/wallet-react-ui' -import { useConnect } from 'wagmi' - -export function WalletLogin() { - const { connect, connectors } = useConnect() - const zeroDevConnector = connectors.find((c) => c.id === 'zerodev-wallet') - - return ( - <> - - - - ) -} -``` - -Once the user finishes authentication, `useAccount` returns the connected address — see the [quickstart](/wallets/quickstart) for a full login component. - -`AuthFlow` supports three fixed sizes: `sm` for compact surfaces, `md` for drawers and smaller modals, and `lg` when the flow has more room. Keep the size fixed across every auth step. The optional `onClose` prop fires when the user clicks the kit's close button — use it when your app owns surrounding UI state, such as closing a modal: - -```tsx - setLoginOpen(false)} /> -``` - -## Signing and transactions - -The current Wallet UI Kit package is focused on login. After the user signs in, use the standard Wallet API pages for wallet actions: - -- [Sign a message](/wallets/wallet-api/sign-message) -- [Send a transaction](/wallets/wallet-api/send-transaction) -- [Batch transactions](/wallets/wallet-api/batch-transactions) - -For post-login profile data, use `useAuthenticators` from `@zerodev/wallet-react` to read the user's linked email contacts, OAuth identities, passkeys, and API-key authenticators. - -Prebuilt signature and transaction confirmation screens are coming soon. Reach out to the [ZeroDev sales team](https://zerodev.app/contact) if you want early access. - -## Coming soon - -The Wallet UI Kit will add more prebuilt wallet components and screens over time, including onramps, asset management and portfolio views, transaction history, and chain-abstracted balances. To request early access, reach out to the [ZeroDev sales team](https://zerodev.app/contact). - -## Next steps - -- [Send a transaction](/wallets/wallet-api/send-transaction) -- [Sign a message](/wallets/wallet-api/sign-message) -- Integrate other login methods: [Passkeys](/wallets/auth/passkeys), [Email OTP](/wallets/auth/email-otp), [Magic Link](/wallets/auth/magic-link), or [Google OAuth](/wallets/auth/google-oauth) diff --git a/docs/pages/wallets/auth/wallet-ui-kit/coming-soon.mdx b/docs/pages/wallets/auth/wallet-ui-kit/coming-soon.mdx new file mode 100644 index 0000000..f29f496 --- /dev/null +++ b/docs/pages/wallets/auth/wallet-ui-kit/coming-soon.mdx @@ -0,0 +1,11 @@ +# Coming soon + +The Wallet UI Kit will add more prebuilt wallet components and screens over time, including: + +- Prebuilt signature and transaction confirmation screens +- Onramps +- Asset management and portfolio views +- Transaction history +- Chain-abstracted balances + +To request early access, reach out to the [ZeroDev sales team](https://zerodev.app/contact). diff --git a/docs/pages/wallets/auth/wallet-ui-kit/connect-wallet.mdx b/docs/pages/wallets/auth/wallet-ui-kit/connect-wallet.mdx new file mode 100644 index 0000000..41e4aea --- /dev/null +++ b/docs/pages/wallets/auth/wallet-ui-kit/connect-wallet.mdx @@ -0,0 +1,89 @@ +# ConnectWallet + +`` renders the current authentication step (sign-up, email verification, OTP, and so on) inside the kit's card. Render it in the Wagmi provider tree; it shows the active screen while the connector waits for the user to finish. + +Out of the box it renders the canonical sign-up page — passkey, Google, and email — so the bare component is all you need to ship a login: + +```tsx + +``` + +## Props + +| Prop | Type | Description | +| --- | --- | --- | +| `size` | `'sm' \| 'md' \| 'lg'` | Card size. `sm` for compact surfaces, `md` for drawers and smaller modals, `lg` when the flow has more room. Keep it fixed across every auth step. | +| `logo` | `ReactNode` | Brand mark shown in the top nav on the sign-up page. When omitted, no logo is shown. | +| `renderSignUp` | `() => ReactNode` | Replace the default sign-up page with your own `SignUp` composition (see below). | +| `onClose` | `() => void` | Fires when the user clicks the kit's close button. Use it when your app owns surrounding UI state, such as closing a modal. | + +```tsx +} + onClose={() => setLoginOpen(false)} +/> +``` + +## Choosing the email flow + +The email method sends either a one-time code (`otp`) or a magic link (`magicLink`, the default). To keep the default page but change the email flow, render `SignUp.Default` — the canonical page — through `renderSignUp` and set `emailAuthMethod`: + +```tsx +import { ConnectWallet, SignUp } from '@zerodev/wallet-react-ui' + + } +/> +``` + +`SignUp.Default` accepts the sign-up page's options: + +| Prop | Type | Description | +| --- | --- | --- | +| `emailAuthMethod` | `'magicLink' \| 'otp'` | Email verification flow. Defaults to `magicLink`. | +| `termsAndConditionsUrl` | `string` | When set, a consent checkbox appears in the footer and every method is blocked until the user agrees. | +| `privacyPolicyUrl` | `string` | Adds a privacy policy link to the footer. Also enables the consent gate. | + +```tsx + ( + + )} +/> +``` + +## Rearranging the sign-up page + +For full control over which methods appear and in what order, compose the page yourself from the `SignUp.*` units inside `renderSignUp`. Options that apply to the whole page — `emailAuthMethod`, `termsAndConditionsUrl`, `privacyPolicyUrl` — go on the `SignUp` root: + +```tsx +import { ConnectWallet, SignUp } from '@zerodev/wallet-react-ui' + + ( + + + + + + )} +/> +``` + +Available units: + +| Unit | Renders | +| --- | --- | +| `SignUp.Passkey` | Create-a-passkey and log-in-with-passkey buttons. | +| `SignUp.Google` | Google OAuth row. | +| `SignUp.Email` | Email input that runs the flow set by `emailAuthMethod`. | +| `SignUp.Divider` | A labelled divider (`or` by default; pass `label` to change it). | + +While one method's authentication is in flight, the other units disable themselves so two flows can't run at once. Include only the units for the methods enabled on your project. + +Authentication success and failure surface through Wagmi — `await` the `connect` call, or watch `useAccount()`. diff --git a/docs/pages/wallets/auth/wallet-ui-kit/getting-started.mdx b/docs/pages/wallets/auth/wallet-ui-kit/getting-started.mdx new file mode 100644 index 0000000..9e0ad64 --- /dev/null +++ b/docs/pages/wallets/auth/wallet-ui-kit/getting-started.mdx @@ -0,0 +1,42 @@ +# Wallet UI Kit + +The Wallet UI Kit gives you prebuilt React UI for ZeroDev Wallet. Use it when you want a ready-made login flow instead of building every authentication screen yourself. + +The kit uses a Wagmi-compatible ZeroDev connector, so after the user signs in you can use standard Wagmi hooks such as `useAccount`, `useSignMessage`, and `useSendTransaction`. + +For a fully custom UI, use the hook-based authentication pages instead: [Passkeys](/wallets/auth/passkeys), [Email OTP](/wallets/auth/email-otp), [Magic Link](/wallets/auth/magic-link), or [Google OAuth](/wallets/auth/google-oauth). To drive the kit's flow yourself, use the `useAuth` hook from `@zerodev/wallet-react-ui` to read and control the auth state. + +## Getting started + +`` renders the active authentication screen. Connecting through the `zeroDevWallet` connector is what opens the flow, so a minimal login is a connect button plus the component in the same provider tree: + +```tsx +import { ConnectWallet } from '@zerodev/wallet-react-ui' +import { useConnect } from 'wagmi' + +export function WalletLogin() { + const { connect, connectors } = useConnect() + const zeroDevConnector = connectors.find((c) => c.id === 'zerodev-wallet') + + return ( + <> + + + + ) +} +``` + +Once the user finishes authentication, `useAccount` returns the connected address — see the [quickstart](/wallets/quickstart) for a full login component. + +## Before you start + +Open the [ZeroDev Dashboard](https://dashboard.zerodev.app/) and make sure your project has: + +- The app origin on the project's ACL allowlist, such as `http://localhost:3000` for local development. +- The auth methods you plan to show configured for the project. +- At least one enabled network. + +Next, [install the kit and configure Wagmi](/wallets/auth/wallet-ui-kit/installation). diff --git a/docs/pages/wallets/auth/wallet-ui-kit/installation.mdx b/docs/pages/wallets/auth/wallet-ui-kit/installation.mdx new file mode 100644 index 0000000..2356d20 --- /dev/null +++ b/docs/pages/wallets/auth/wallet-ui-kit/installation.mdx @@ -0,0 +1,70 @@ +# Installation + +Install the Wallet UI Kit and its peer dependencies, then add the connector and providers. + +## Install packages + +:::code-group + +```bash [npm] +npm i @zerodev/wallet-react-ui @zerodev/react-ui @zerodev/wallet-core @zerodev/wallet-react wagmi viem @wagmi/core @tanstack/react-query zustand +``` + +```bash [yarn] +yarn add @zerodev/wallet-react-ui @zerodev/react-ui @zerodev/wallet-core @zerodev/wallet-react wagmi viem @wagmi/core @tanstack/react-query zustand +``` + +```bash [pnpm] +pnpm add @zerodev/wallet-react-ui @zerodev/react-ui @zerodev/wallet-core @zerodev/wallet-react wagmi viem @wagmi/core @tanstack/react-query zustand +``` + +```bash [bun] +bun add @zerodev/wallet-react-ui @zerodev/react-ui @zerodev/wallet-core @zerodev/wallet-react wagmi viem @wagmi/core @tanstack/react-query zustand +``` + +::: + +## Configure Wagmi + +Import `zeroDevWallet` from `@zerodev/wallet-react-ui` and add it as a connector. It wraps the base ZeroDev Wallet connector and drives the kit's auth UI. + +```tsx +import { zeroDevWallet } from '@zerodev/wallet-react-ui' +import { createConfig, http } from 'wagmi' +import { arbitrumSepolia } from 'wagmi/chains' + +export const config = createConfig({ + chains: [arbitrumSepolia], + connectors: [ + zeroDevWallet({ + projectId: '', + chains: [arbitrumSepolia], + mode: '7702', + }), + ], + transports: { + [arbitrumSepolia.id]: http('https://sepolia-rollup.arbitrum.io/rpc'), + }, +}) +``` + +## Add providers and styles + +Import the kit stylesheet once at your app entry, then wrap your app with the Wagmi and TanStack Query providers. If your app has broad global element styles, scope them to your own app shell so they don't override the kit. + +```tsx +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' +import '@zerodev/wallet-react-ui/styles.css' +import { WagmiProvider } from 'wagmi' +import { config } from './wagmi' + +const queryClient = new QueryClient() + + + + {/* your app */} + + +``` + +With the connector and providers in place, render the login flow with [`ConnectWallet`](/wallets/auth/wallet-ui-kit/connect-wallet). diff --git a/docs/pages/wallets/index.mdx b/docs/pages/wallets/index.mdx index f94699e..833a794 100644 --- a/docs/pages/wallets/index.mdx +++ b/docs/pages/wallets/index.mdx @@ -6,7 +6,7 @@ Users sign in with familiar login methods, then get a self-custodial web3 wallet ## How it works -Adding ZeroDev Wallet takes three steps. Use the hook-based SDK for a fully custom wallet experience, or drop in the prebuilt [Wallet UI Kit](/wallets/auth/wallet-ui-kit) when you want a ready-made login flow. See it in the [live demo](https://smart-wallet-demo.zerodev.app/), or follow the [quickstart](/wallets/quickstart) to build it yourself. +Adding ZeroDev Wallet takes three steps. Use the hook-based SDK for a fully custom wallet experience, or drop in the prebuilt [Wallet UI Kit](/wallets/auth/wallet-ui-kit/getting-started) when you want a ready-made login flow. See it in the [live demo](https://smart-wallet-demo.zerodev.app/), or follow the [quickstart](/wallets/quickstart) to build it yourself. @@ -31,7 +31,7 @@ That's what makes every wallet **self-custodial**: only the authenticated user c - Authenticate with [passkeys](/wallets/auth/passkeys), [Google OAuth](/wallets/auth/google-oauth), [email OTP](/wallets/auth/email-otp), or [magic links](/wallets/auth/magic-link). - - Drop in the prebuilt [Wallet UI Kit](/wallets/auth/wallet-ui-kit) for a faster login integration with less code. + - Drop in the prebuilt [Wallet UI Kit](/wallets/auth/wallet-ui-kit/getting-started) for a faster login integration with less code. - Let users [export their wallet](/wallets/export) at any time. diff --git a/docs/pages/wallets/quickstart.mdx b/docs/pages/wallets/quickstart.mdx index ecfef41..d3538e0 100644 --- a/docs/pages/wallets/quickstart.mdx +++ b/docs/pages/wallets/quickstart.mdx @@ -2,7 +2,7 @@ Add ZeroDev Wallet to any React app that can render client-side React components. Authenticate users with ZeroDev hooks, then use standard Wagmi hooks for wallet actions. -Want a faster starting point? Try the optional [Wallet UI Kit](/wallets/auth/wallet-ui-kit) for a prebuilt login flow. +Want a faster starting point? Try the optional [Wallet UI Kit](/wallets/auth/wallet-ui-kit/getting-started) for a prebuilt login flow. For a complete working reference, see the [ZeroDev Wallet SDK demo app](https://smart-wallet-demo.zerodev.app/). @@ -275,7 +275,7 @@ Each auth method connects the same ZeroDev Wagmi connector after successful auth ## Optional Wallet UI Kit -The examples above use `@zerodev/wallet-react` so you can build your own UI. If you want a prebuilt login flow, use the optional [Wallet UI Kit](/wallets/auth/wallet-ui-kit). Keep the hook-based path if you want full control over layout, styling, and bundle size. +The examples above use `@zerodev/wallet-react` so you can build your own UI. If you want a prebuilt login flow, use the optional [Wallet UI Kit](/wallets/auth/wallet-ui-kit/getting-started). Keep the hook-based path if you want full control over layout, styling, and bundle size. ## Troubleshooting diff --git a/docs/pages/wallets/wallet-api/batch-transactions.mdx b/docs/pages/wallets/wallet-api/batch-transactions.mdx index d45d7f0..5d33d96 100644 --- a/docs/pages/wallets/wallet-api/batch-transactions.mdx +++ b/docs/pages/wallets/wallet-api/batch-transactions.mdx @@ -87,4 +87,4 @@ export function BatchCalls({ - [Send a transaction](/wallets/wallet-api/send-transaction) - [Sign a message](/wallets/wallet-api/sign-message) -- [Wallet UI Kit](/wallets/auth/wallet-ui-kit) +- [Wallet UI Kit](/wallets/auth/wallet-ui-kit/getting-started) diff --git a/vocs.config.tsx b/vocs.config.tsx index 74a47a0..ad3cd42 100644 --- a/vocs.config.tsx +++ b/vocs.config.tsx @@ -575,7 +575,25 @@ export default defineConfig({ }, { text: "Wallet UI Kit", - link: "/wallets/auth/wallet-ui-kit", + collapsed: true, + items: [ + { + text: "Getting Started", + link: "/wallets/auth/wallet-ui-kit/getting-started", + }, + { + text: "Installation", + link: "/wallets/auth/wallet-ui-kit/installation", + }, + { + text: "ConnectWallet", + link: "/wallets/auth/wallet-ui-kit/connect-wallet", + }, + { + text: "Coming Soon", + link: "/wallets/auth/wallet-ui-kit/coming-soon", + }, + ], }, { text: "React Native",