@lykhoyda/gelato-wallet-ui

Production-ready React component library for Web3 wallet interfaces with Gelato SDK integration. Build gasless Web3 experiences with beautiful, customizable components.

📚 Storybook

This library includes a comprehensive Storybook for interactive component development and testing. Storybook provides a visual catalog of all components with their various states and configurations.

Running Storybook

# Start Storybook development server
yarn storybook

# Storybook will open automatically at http://localhost:6006

Building Storybook

# Build static Storybook for deployment
yarn build-storybook

# Output will be in storybook-static/ directory

Available Stories

• WalletCard - Multiple states including empty, loading, and rich wallet displays
• ActivityLog - Transaction history with pending, success, and error states
• GasEstimationModal - Gas estimation flows for USDC and WETH payments

Each component story includes:

• Interactive controls to modify props
• Multiple pre-configured states
• Responsive preview at different viewport sizes
• Documentation and usage examples

Visit Storybook to explore all components and their variations interactively!

Features

• 🎨 Beautiful Components - Pre-built wallet UI components with dark theme
• ⛽ Gasless Transactions - Built-in support for sponsored transactions
• 🔐 Smart Wallet Support - Seamless integration with Gelato Smart Wallets
• 🎯 TypeScript First - Full type safety and IntelliSense support
• 📦 Tree Shakeable - Import only what you need
• 🚀 Production Ready - Battle-tested error handling and edge cases
• 🌙 Dark Mode - Built-in dark mode support
• ⚡ TypeScript - Full type safety
• ⚛️ React 19 - Built for the latest React features
• 📚 Interactive Storybook - Explore all components with live examples

Installation

Note: This library requires React 19 or higher.

yarn add @lykhoyda/gelato-wallet-ui
# or
npm install @lykhoyda/gelato-wallet-ui
# or
pnpm add @lykhoyda/gelato-wallet-ui

⚠️ Required Configuration

This library does NOT include any API keys or environment variables.

Your application MUST provide:

• sponsorApiKey - Get from app.gelato.network
• dynamicEnvironmentId - Get from app.gelato.cloud/wallets or app.dynamic.xyz

The library will throw errors if these are not provided. The default network is Ink Sepolia; you can opt into additional chains via the chains prop.

Quick Start

Step 1: Setup Provider with Required Configuration

import { GelatoProvider, GelatoSmartWalletConnectButton } from '@lykhoyda/gelato-wallet-ui';
import '@lykhoyda/gelato-wallet-ui/style.css';

// Your app must provide these values (e.g., from your .env file)
const GELATO_CONFIG = {
  sponsorApiKey: process.env.NEXT_PUBLIC_GELATO_API_KEY!, // Required
  dynamicEnvironmentId: process.env.NEXT_PUBLIC_DYNAMIC_ID!, // Required
  rpcUrl: process.env.NEXT_PUBLIC_RPC_URL, // Optional (applies to all chains)
};

function App() {
  return (
    <GelatoProvider config={GELATO_CONFIG}>
      {/* REQUIRED: Use SDK's button for authentication */}
      <GelatoSmartWalletConnectButton>
        <button className="px-4 py-2 bg-purple-600 rounded">Connect Wallet</button>
      </GelatoSmartWalletConnectButton>
    </GelatoProvider>
  );
}

Step 2: Add Components

import { WalletCard, ActivityLog } from '@lykhoyda/gelato-wallet-ui';

function Dashboard() {
  return (
    <>
      <WalletCard />
      <ActivityLog />
    </>
  );
}

Components

WalletCard

Main wallet interface component showing connection status, balance, and actions.

<WalletCard showBalances={true} showNetwork={true} />

GasEstimationModal

Modal for displaying and selecting gas payment options.

<GasEstimationModal isOpen={isOpen} onClose={() => setIsOpen(false)} estimatedGas={gasAmount} />

ActivityLog

Transaction history and activity display with automatic fetching from useMintToken hook.

<ActivityLog maxEntries={5} />

Multi-Chain Setup

By default, GelatoProvider configures the SDK for Ink Sepolia. To support additional networks, pass the chains prop with any viem chains (for example, Base Sepolia and Sepolia):

import { GelatoProvider, GelatoSmartWalletConnectButton } from '@lykhoyda/gelato-wallet-ui';
import { inkSepolia, baseSepolia, sepolia } from 'viem/chains';

const GELATO_CONFIG = {
  sponsorApiKey: process.env.NEXT_PUBLIC_GELATO_API_KEY!,
  dynamicEnvironmentId: process.env.NEXT_PUBLIC_DYNAMIC_ID!,
};

export function App() {
  return (
    <GelatoProvider config={GELATO_CONFIG} chains={[inkSepolia, baseSepolia, sepolia]}>
      <GelatoSmartWalletConnectButton>
        <button className="px-4 py-2 bg-purple-600 rounded">Connect Wallet</button>
      </GelatoSmartWalletConnectButton>
    </GelatoProvider>
  );
}

Notes:

• The library still defaults to Ink Sepolia when chains is omitted.
• Switching between networks happens via the SDK’s switchNetwork from the provider context or via your own UI.

Hooks

useGelatoClient

Primary hook for accessing the Gelato client and session state.

Note: The SDK does not expose a programmatic connect API. Use <GelatoSmartWalletConnectButton> to open the authentication modal.

import { useGelatoClient, ConnectButton } from '@lykhoyda/gelato-wallet-ui';

function Actions() {
  const { client, account, isConnected, logout, switchNetwork } = useGelatoClient();

  if (!client || !account || !isConnected) {
    return <ConnectButton />;
  }

  // Example: switch network or logout
  return (
    <div>
      <button onClick={() => switchNetwork?.(763373)}>Switch to Ink Sepolia</button>
      <button onClick={() => logout()}>Logout</button>
    </div>
  );
}

useMintToken

Hook for minting tokens with gasless transactions.

const { mintSponsored, mintWithERC20, isMinting, error } = useMintToken();

// Gasless minting (sponsored)
await mintSponsored();

// Or pay with ERC-20 tokens
await mintWithERC20('USDC');

Development

# Install dependencies
yarn install

# Start development server
yarn dev

# Build library
yarn build

# Type check
yarn type-check

# Run linter
yarn lint

📚 Storybook

This library includes a comprehensive Storybook for interactive component development and testing. Storybook provides a visual catalog of all components with their various states and configurations.

Running Storybook

# Start Storybook development server
yarn storybook

# Storybook will open automatically at http://localhost:6006

Building Storybook

# Build static Storybook for deployment
yarn build-storybook

# Output will be in storybook-static/ directory

Available Stories

• WalletCard - Multiple states including empty, loading, and rich wallet displays
• ActivityLog - Transaction history with pending, success, and error states
• GasEstimationModal - Gas estimation flows for USDC and WETH payments

Each component story includes:

• Interactive controls to modify props
• Multiple pre-configured states
• Responsive preview at different viewport sizes
• Documentation and usage examples

Visit Storybook to explore all components and their variations interactively!

Architecture

This library is built with:

• Vite - Fast build tool and dev server
• React 19 - Latest React with support for Server Components and Actions
• TypeScript - Full type safety
• Tailwind CSS v4 - Latest version with Oxide engine, using gwui prefix for style isolation
• Viem - Ethereum interface

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

License

MIT © Gelato Network

Links

• Documentation
• Demo App
• GitHub