ycdirectory-ui

A modern React UI component library with built-in wallet connectivity. Built with TypeScript, Tailwind CSS, and comprehensive Web3 integration.

🚀 Features

🎨 UI Components

• Modern Design: Clean, responsive components built with Tailwind CSS
• TypeScript: Full type safety and excellent developer experience
• Customizable: Easy to customize with Tailwind classes
• Tree-shakable: Only import what you need

🔗 Wallet Integration

• Multiple Wallets: MetaMask, OKX, Coinbase, Rabby, Trust Wallet
• EIP-6963 Standard: Modern wallet detection
• Chain Switching: Support for Ethereum, Polygon, BSC, Arbitrum, Optimism
• Balance Tracking: Real-time balance updates with caching
• Token Support: ERC-20 token balance queries
• Auto-Reconnect: Seamless reconnection on page refresh

📦 Installation

npm install ycdirectory-ui
# or
yarn add ycdirectory-ui
# or
pnpm add ycdirectory-ui

🏁 Quick Start

Basic Setup

import { WalletProvider, EnhancedConnectButton } from 'ycdirectory-ui';
import 'ycdirectory-ui/dist/index.css'; // Import styles

function App() {
  return (
    <WalletProvider
      config={{
        appName: "My App",
        projectId: "your-project-id"
      }}
    >
      <EnhancedConnectButton
        showBalance={true}
        showChainSwitcher={true}
      />
    </WalletProvider>
  );
}

Custom Integration

import { Button, useWallet, WalletProvider } from 'ycdirectory-ui';

function CustomWalletButton() {
  const {
    isConnected,
    isConnecting,
    address,
    balance,
    connect,
    disconnect,
    switchChain
  } = useWallet();

  if (isConnected) {
    return (
      <div className="flex items-center gap-4">
        <span>{address?.slice(0, 6)}...{address?.slice(-4)}</span>
        <span>{balance} ETH</span>
        <Button onClick={disconnect} variant="outline">
          Disconnect
        </Button>
      </div>
    );
  }

  return (
    <Button onClick={() => connect('metamask')} disabled={isConnecting}>
      {isConnecting ? 'Connecting...' : 'Connect Wallet'}
    </Button>
  );
}

📚 Components

UI Components

Button

import { Button } from 'ycdirectory-ui';

<Button variant="primary" size="lg" onClick={handleClick}>
  Click me
</Button>

Props:

• variant: 'primary' | 'secondary' | 'outline' | 'ghost'
• size: 'sm' | 'md' | 'lg'
• disabled: boolean
• className: string

Card

import { Card } from 'ycdirectory-ui';

<Card className="p-6">
  <h3>Card Title</h3>
  <p>Card content</p>
</Card>

Input

import { Input } from 'ycdirectory-ui';

<Input
  placeholder="Enter value"
  value={value}
  onChange={setValue}
/>

Badge

import { Badge } from 'ycdirectory-ui';

<Badge variant="success">Active</Badge>

Wallet Components

WalletProvider

The root provider that manages wallet state.

import { WalletProvider } from 'ycdirectory-ui';

<WalletProvider
  config={{
    appName: "Your App Name",
    projectId: "your-walletconnect-project-id", // Optional
    chains: [mainnet, polygon], // Optional
    autoConnect: true, // Optional
  }}
>
  {children}
</WalletProvider>

EnhancedConnectButton

A complete wallet connection button with built-in UI.

import { EnhancedConnectButton } from 'ycdirectory-ui';

<EnhancedConnectButton
  showBalance={true}
  showChainSwitcher={true}
  size="md"
  variant="primary"
  onConnect={(result) => console.log('Connected:', result)}
  onDisconnect={() => console.log('Disconnected')}
/>

AccountDropdown

A dropdown showing account info with actions.

import { AccountDropdown } from 'ycdirectory-ui';

<AccountDropdown
  showBalance={true}
  showChainSwitcher={true}
  size="md"
/>

🪝 Hooks

useWallet

The main hook for wallet functionality.

import { useWallet } from 'ycdirectory-ui';

const {
  // Connection state
  isConnected,
  isConnecting,
  isDisconnected,

  // Wallet info
  address,
  chainId,
  balance,
  wallet,

  // Actions
  connect,
  disconnect,
  switchChain,

  // UI controls
  openModal,
  closeModal,

  // Balance management
  fetchBalance,
  balanceLoading,
  getTokenBalance,

  // Wallet detection
  walletInstances,
  detectedWallets,
  walletsLoading,
} = useWallet();

Examples

Connect to specific wallet

const { connect } = useWallet();

// Connect to MetaMask
await connect('metamask');

// Connect to OKX
await connect('okx');

Switch network

const { switchChain } = useWallet();

// Switch to Polygon
await switchChain(137);

// Switch to BSC
await switchChain(56);

Get token balance

const { getTokenBalance } = useWallet();

const tokenBalance = await getTokenBalance('0x...'); // ERC-20 contract address
console.log(tokenBalance.balance, tokenBalance.symbol);

🌐 Supported Networks

• Ethereum Mainnet (1)
• Sepolia Testnet (11155111)
• Polygon (137)
• BNB Smart Chain (56)
• Arbitrum One (42161)
• Optimism (10)

🔗 Supported Wallets

• MetaMask - Browser extension
• OKX Wallet - Browser extension
• Coinbase Wallet - Browser extension
• Rabby Wallet - Browser extension
• Trust Wallet - Browser extension
• WalletConnect - Mobile wallets (coming soon)

🎨 Styling

This library uses Tailwind CSS. Make sure to include Tailwind in your project:

npm install tailwindcss

Or import the pre-built styles:

import 'ycdirectory-ui/dist/index.css';

📖 Advanced Usage

Custom Wallet Modal

import { useWallet, WalletModal } from 'ycdirectory-ui';

function CustomWalletFlow() {
  const {
    openModal,
    closeModal,
    isModalOpen,
    walletInstances,
    connect
  } = useWallet();

  return (
    <>
      <button onClick={openModal}>
        Connect Wallet
      </button>

      <WalletModal
        isOpen={isModalOpen}
        onClose={closeModal}
        onConnect={connect}
        title="Choose Your Wallet"
        walletInstances={walletInstances}
      />
    </>
  );
}

Error Handling

const { connect, error } = useWallet();

const handleConnect = async () => {
  try {
    await connect('metamask');
  } catch (err) {
    console.error('Connection failed:', err);
  }
};

if (error) {
  return <div>Error: {error.message}</div>;
}

Event Listening

useEffect(() => {
  const { address, chainId } = useWallet();

  console.log('Wallet connected:', { address, chainId });
}, [address, chainId]);

🔧 Development

# Install dependencies
pnpm install

# Start development
pnpm dev

# Build
pnpm build

# Start Storybook
pnpm storybook

# Run tests
pnpm test

📄 License

MIT © YCDirectory

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Storybook

Made with ❤️ by the YCDirectory team