@lykhoyda/gelato-wallet-ui/README.md

Production-ready React Smart components for Web3 wallet interfaces with Gelato SDK integration

# @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.

[![npm version](https://img.shields.io/npm/v/@lykhoyda/gelato-wallet-ui.svg)](https://www.npmjs.com/package/@lykhoyda/gelato-wallet-ui)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# 📚 Storybook

<p align="center">
  <img src="https://raw.githubusercontent.com/storybookjs/brand/master/badge/badge-storybook.svg" alt="Storybook" width="200"/>
</p>

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

```bash
# Start Storybook development server
yarn storybook

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

### Building Storybook

```bash
# 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.

```bash
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](https://app.gelato.network)
- **dynamicEnvironmentId** - Get from [app.gelato.cloud/wallets](https://app.gelato.cloud/wallets) or [app.dynamic.xyz](https://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

```tsx
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

```tsx
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.

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

### GasEstimationModal

Modal for displaying and selecting gas payment options.

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

### ActivityLog

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

```tsx
<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):

```tsx
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.

```tsx
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.

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

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

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

## Development

```bash
# 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

```bash
# Start Storybook development server
yarn storybook

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

### Building Storybook

```bash
# 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](https://docs.gelato.network/wallet-ui)
- [Demo App](https://gelato-wallet-demo.vercel.app)
- [GitHub](https://github.com/gelato-network/gelato-wallet-ui)