CompactWalletOverview

Space-efficient wallet overview component that displays balance and status in a compact format, perfect for sidebars and widgets

A space-efficient wallet overview component that displays balance and status in a compact format, perfect for sidebars, widgets, and constrained layouts. Unlike the full WalletOverview, this component focuses purely on displaying balance information without action buttons.

View Component Preview →

Installation

npx bigblocks add compact-wallet-overview

Import

import { CompactWalletOverview } from 'bigblocks';

Props

Prop	Type	Required	Default	Description
balance	`BSVBalance`	No	-	Wallet balance object with confirmed, unconfirmed, and total amounts
showValues	`boolean`	No	`true`	Whether to show balance values or hide for privacy
currency	`'BSV' \| 'USD'`	No	`'BSV'`	Display currency format
exchangeRate	`number`	No	-	BSV to USD exchange rate for conversion
className	`string`	No	-	Additional CSS classes

BSVBalance Interface

interface BSVBalance {
  confirmed: number;      // Confirmed satoshis
  unconfirmed: number;    // Pending satoshis  
  total: number;          // Total satoshis
}

Basic Usage

import { CompactWalletOverview } from 'bigblocks';

export default function Sidebar() {
  return (
    <div className="sidebar">
      <h3>Wallet</h3>
      <CompactWalletOverview />
    </div>
  );
}

Advanced Usage

With Custom Balance

import { CompactWalletOverview } from 'bigblocks';

export default function WalletWidget() {
  const balance = {
    confirmed: 150000000,    // 1.5 BSV confirmed
    unconfirmed: 5000000,    // 0.05 BSV pending
    total: 155000000         // 1.55 BSV total
  };

  return (
    <CompactWalletOverview 
      balance={balance}
      showValues={true}
      currency="BSV"
    />
  );
}

USD Display with Exchange Rate

import { CompactWalletOverview } from 'bigblocks';
import { useState, useEffect } from 'react';

export default function USDWalletWidget() {
  const [exchangeRate, setExchangeRate] = useState<number>();
  
  useEffect(() => {
    // Fetch current BSV/USD rate
    fetch('/api/market/bsv-price')
      .then(res => res.json())
      .then(data => setExchangeRate(data.usd));
  }, []);

  return (
    <CompactWalletOverview 
      currency="USD"
      exchangeRate={exchangeRate}
      showValues={true}
    />
  );
}

Privacy Mode Toggle

import { CompactWalletOverview } from 'bigblocks';
import { useState } from 'react';

export default function PrivacyWallet() {
  const [showValues, setShowValues] = useState(false);

  return (
    <div className="wallet-container">
      <div className="flex justify-between items-center mb-2">
        <h4>Balance</h4>
        <button 
          onClick={() => setShowValues(!showValues)}
          className="text-xs opacity-60 hover:opacity-100"
        >
          {showValues ? '👁️' : '🔒'}
        </button>
      </div>
      
      <CompactWalletOverview 
        showValues={showValues}
        currency="BSV"
      />
    </div>
  );
}

Common Patterns

import { CompactWalletOverview } from 'bigblocks';

export default function DashboardWidget() {
  return (
    <div className="bg-white rounded-lg p-4 shadow">
      <div className="flex items-center justify-between mb-3">
        <h3 className="text-sm font-medium text-gray-900">My Wallet</h3>
        <span className="text-xs text-gray-500">BSV</span>
      </div>
      
      <CompactWalletOverview 
        currency="BSV"
        className="mb-3"
      />
      
      <div className="flex space-x-2">
        <button className="flex-1 text-xs bg-orange-100 text-orange-800 px-2 py-1 rounded">
          Send
        </button>
        <button className="flex-1 text-xs bg-green-100 text-green-800 px-2 py-1 rounded">
          Receive
        </button>
      </div>
    </div>
  );
}

import { CompactWalletOverview } from 'bigblocks';

export default function MobileNavBar() {
  return (
    <nav className="fixed bottom-0 left-0 right-0 bg-white border-t">
      <div className="flex items-center justify-between px-4 py-2">
        <div className="text-xs">
          <CompactWalletOverview 
            currency="USD"
            showValues={true}
            className="text-xs"
          />
        </div>
        
        <div className="flex space-x-4">
          <button>Home</button>
          <button>Send</button>
          <button>Receive</button>
          <button>Settings</button>
        </div>
      </div>
    </nav>
  );
}

Header Balance Display

import { CompactWalletOverview } from 'bigblocks';

export default function AppHeader() {
  return (
    <header className="bg-gray-900 text-white px-4 py-3">
      <div className="flex items-center justify-between">
        <h1 className="text-xl font-bold">Bitcoin App</h1>
        
        <div className="flex items-center space-x-4">
          <CompactWalletOverview 
            currency="BSV"
            showValues={true}
            className="text-white"
          />
          
          <button className="text-sm bg-orange-600 px-3 py-1 rounded">
            Account
          </button>
        </div>
      </div>
    </header>
  );
}

Responsive Layout

import { CompactWalletOverview } from 'bigblocks';

export default function ResponsiveWallet() {
  return (
    <div className="wallet-responsive">
      {/* Desktop: Show in sidebar */}
      <div className="hidden md:block md:w-64 bg-gray-50 p-4">
        <h3 className="font-semibold mb-3">Wallet Overview</h3>
        <CompactWalletOverview 
          currency="BSV"
          showValues={true}
        />
      </div>
      
      {/* Mobile: Show in header */}
      <div className="md:hidden bg-white p-3 border-b">
        <div className="flex justify-between items-center">
          <span className="text-sm font-medium">Balance</span>
          <CompactWalletOverview 
            currency="USD"
            showValues={true}
            className="text-sm"
          />
        </div>
      </div>
    </div>
  );
}

Authentication Requirements

The CompactWalletOverview component requires Bitcoin authentication context to automatically fetch balance data:

import { BitcoinAuthProvider, BitcoinQueryProvider, CompactWalletOverview } from 'bigblocks';

function App() {
  return (
    <BitcoinQueryProvider>
      <BitcoinAuthProvider config={{ apiUrl: '/api' }}>
        <CompactWalletOverview />
      </BitcoinAuthProvider>
    </BitcoinQueryProvider>
  );
}

Data Integration

Automatic Balance Fetching

When no balance prop is provided, the component automatically fetches balance from the authenticated user's wallet:

// Automatically uses authenticated user's balance
<CompactWalletOverview />

// Override with custom balance
<CompactWalletOverview 
  balance={{
    confirmed: 100000000,
    unconfirmed: 0,
    total: 100000000
  }}
/>

Real-time Updates

The component automatically updates when balance changes through Bitcoin transactions:

import { CompactWalletOverview } from 'bigblocks';
import { useBitcoinAuth } from 'bigblocks';

export default function LiveWallet() {
  const { user } = useBitcoinAuth();
  
  return (
    <div>
      <h3>Live Balance for {user?.address}</h3>
      <CompactWalletOverview />
      {/* Balance updates automatically when transactions complete */}
    </div>
  );
}

API Integration

The component integrates with the following API endpoints:

Get Wallet Balance

GET /api/wallet/balance

Response:
{
  success: boolean;
  balance: {
    confirmed: number;      // Confirmed satoshis
    unconfirmed: number;    // Pending satoshis
    total: number;          // Total satoshis
  };
  address: string;
  lastUpdated: number;
}

Get Exchange Rate (for USD display)

GET /api/market/bsv-price

Response:
{
  success: boolean;
  price: {
    usd: number;           // Current BSV/USD rate
    change24h: number;     // 24h change percentage
    lastUpdated: number;   // Price timestamp
  };
}

Styling and Theming

Custom Styling

<CompactWalletOverview 
  className="custom-wallet-style"
  currency="BSV"
/>

.custom-wallet-style {
  background: linear-gradient(135deg, #f7931a 0%, #ff6b35 100%);
  color: white;
  padding: 1rem;
  border-radius: 8px;
  font-weight: 600;
}

.custom-wallet-style .balance-amount {
  font-size: 1.25rem;
  font-weight: 700;
}

.custom-wallet-style .balance-label {
  opacity: 0.8;
  font-size: 0.875rem;
}

Theme Integration

import { CompactWalletOverview, BitcoinThemeProvider } from 'bigblocks';

function ThemedApp() {
  return (
    <BitcoinThemeProvider theme="orange">
      <CompactWalletOverview 
        currency="BSV"
        className="themed-wallet"
      />
    </BitcoinThemeProvider>
  );
}

Accessibility

The component includes proper accessibility features:

Screen reader support: Balance values are announced properly
Keyboard navigation: Focusable when interactive
High contrast: Respects system color preferences
Reduced motion: Respects prefers-reduced-motion settings

<CompactWalletOverview 
  currency="BSV"
  aria-label="Current wallet balance"
  role="region"
/>

Performance Considerations

Optimization Tips

Memoization: The component automatically memoizes balance calculations
Update Frequency: Balance updates are debounced to prevent excessive re-renders
Currency Conversion: Exchange rates are cached for performance

import { memo } from 'react';
import { CompactWalletOverview } from 'bigblocks';

// Memoize for performance in lists or frequent updates
const MemoizedWallet = memo(CompactWalletOverview);

export default function WalletList({ wallets }) {
  return (
    <div>
      {wallets.map(wallet => (
        <MemoizedWallet 
          key={wallet.address}
          balance={wallet.balance}
          currency="BSV"
        />
      ))}
    </div>
  );
}

Troubleshooting

Common Issues

Balance not displaying

Ensure BitcoinAuthProvider is configured with valid API URL
Verify user is authenticated
Check API endpoint is returning valid balance data

USD conversion not working

Provide exchangeRate prop or ensure /api/market/bsv-price endpoint exists
Check exchange rate API is accessible and returning valid data

Component not updating

Verify BitcoinQueryProvider is wrapping the component
Check that balance updates are being propagated through React Query
Ensure API responses include proper cache headers

Error Handling

import { CompactWalletOverview } from 'bigblocks';
import { ErrorBoundary } from 'react-error-boundary';

function WalletErrorFallback({ error }) {
  return (
    <div className="wallet-error">
      <span>Balance unavailable</span>
      <button onClick={() => window.location.reload()}>
        Retry
      </button>
    </div>
  );
}

export default function SafeWallet() {
  return (
    <ErrorBoundary FallbackComponent={WalletErrorFallback}>
      <CompactWalletOverview currency="BSV" />
    </ErrorBoundary>
  );
}

WalletOverview - Full wallet view with actions and transaction history
TokenBalance - Display token balances
SendBSVButton - Send BSV functionality
SimpleTokenBalance - Simplified token display

API Reference

Component Props Type

interface CompactWalletOverviewProps {
  balance?: BSVBalance;
  showValues?: boolean;
  currency?: 'BSV' | 'USD';
  exchangeRate?: number;
  className?: string;
}

interface BSVBalance {
  confirmed: number;      // Confirmed satoshis
  unconfirmed: number;    // Pending satoshis
  total: number;          // Total satoshis
}

Usage with React Query

import { useQuery } from '@tanstack/react-query';
import { CompactWalletOverview } from 'bigblocks';

function WalletWithQuery() {
  const { data: balance } = useQuery({
    queryKey: ['wallet-balance'],
    queryFn: () => fetch('/api/wallet/balance').then(res => res.json()),
    refetchInterval: 30000 // Refresh every 30 seconds
  });

  return (
    <CompactWalletOverview 
      balance={balance}
      currency="BSV"
    />
  );
}