JSPM

@txnlab/use-wallet-ui-react

0.3.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 8
  • Score
    100M100P100Q59356F
  • License MIT

React components for use-wallet UI

Package Exports

  • @txnlab/use-wallet-ui-react
  • @txnlab/use-wallet-ui-react/dist/style.css
  • @txnlab/use-wallet-ui-react/package.json

Readme

@txnlab/use-wallet-ui-react

Ready-to-use UI components for Algorand wallet integration, built as a companion to @txnlab/use-wallet.

npm version License: MIT

Quick Start

npm install @txnlab/use-wallet-ui-react

This package provides polished UI components that work on top of @txnlab/use-wallet-react. Choose the setup that matches your project:

If you're using Tailwind CSS

import {
  NetworkId,
  WalletId,
  WalletManager,
  WalletProvider,
} from '@txnlab/use-wallet-react'
import { WalletUIProvider, WalletButton } from '@txnlab/use-wallet-ui-react'

// Configure the wallets you want to use
const walletManager = new WalletManager({
  wallets: [
    WalletId.PERA,
    WalletId.DEFLY,
    WalletId.LUTE,
    // Add more wallets as needed
  ],
  defaultNetwork: NetworkId.MAINNET,
})

function App() {
  return (
    <WalletProvider manager={walletManager}>
      <WalletUIProvider>
        <div>
          <WalletButton />
        </div>
      </WalletUIProvider>
    </WalletProvider>
  )
}

If you're NOT using Tailwind CSS

import {
  NetworkId,
  WalletId,
  WalletManager,
  WalletProvider,
} from '@txnlab/use-wallet-react'
import { WalletUIProvider, WalletButton } from '@txnlab/use-wallet-ui-react'
// Import our pre-built styles
import '@txnlab/use-wallet-ui-react/dist/style.css'

// Configure the wallets you want to use
const walletManager = new WalletManager({
  wallets: [
    WalletId.PERA,
    WalletId.DEFLY,
    WalletId.LUTE,
    // Add more wallets as needed
  ],
  defaultNetwork: NetworkId.MAINNET,
})

function App() {
  return (
    <WalletProvider manager={walletManager}>
      <WalletUIProvider>
        {/* Add data-wallet-ui attribute when not using Tailwind */}
        <div data-wallet-ui>
          <WalletButton />
        </div>
      </WalletUIProvider>
    </WalletProvider>
  )
}

That's it! You now have a fully functional wallet connection system with:

  • Clean, accessible UI components
  • NFD integration
  • ALGO balance display
  • Account switching
  • Dark/light mode support

Note: This is the React implementation of the UI components. Future versions will support Vue and SolidJS to match all frameworks supported by the core @txnlab/use-wallet library.

Table of Contents

Dependencies

Required

  • @txnlab/use-wallet-react v4
  • algosdk v3 (required for use-wallet v4)
  • React v18 or v19

Optional & Integrated

  • Tanstack Query: Used internally for NFD lookups (built-in, but can integrate with your existing setup)
  • Tailwind CSS: Supported but not required (the library works with or without it)

Installation

# npm
npm install @txnlab/use-wallet-ui-react

# yarn
yarn add @txnlab/use-wallet-ui-react

# pnpm
pnpm add @txnlab/use-wallet-ui-react

Styling Options

The library supports two styling approaches:

Using Tailwind CSS provides the richest customization experience:

  • Full access to Tailwind's utility classes for customization
  • Hover, focus, and active states with simple modifiers
  • Dark mode support with the dark: variant
  • Responsive design with breakpoint prefixes
  • Animation and transition utilities
  • Theme customization through your Tailwind config

With Tailwind CSS v4

/* In your CSS file */
@import 'tailwindcss';
@source "../node_modules/@txnlab/use-wallet-ui-react";

This uses the @source directive to tell Tailwind to scan our library for classes. See the Tailwind CSS v4 Installation Guide for setup instructions.

With Tailwind CSS v3

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    // Add this line to scan our components
    './node_modules/@txnlab/use-wallet-ui-react/dist/**/*.{js,ts,jsx,tsx}',
  ],
  // ...rest of your config
}

See the Tailwind CSS v3 Installation Guide for setup instructions.

Option 2: Using the Pre-built CSS

For projects that don't use Tailwind, we provide a pre-built CSS file:

// 1. Import the pre-built CSS
import '@txnlab/use-wallet-ui-react/dist/style.css'

function App() {
  return (
    // 2. Add the data-wallet-ui attribute to any container with wallet components
    <div data-wallet-ui>
      <WalletButton />
    </div>
  )
}

Important: Add the data-wallet-ui attribute to scope our styles and prevent conflicts with your application's existing styles.

While this approach offers less flexibility for customization compared to Tailwind, it provides a simple way to use the components with minimal setup.

Basic Usage

This library builds on top of @txnlab/use-wallet-react to provide UI components for wallet connectivity. Here's the basic setup:

1. Set up the Providers

import {
  NetworkId,
  WalletId,
  WalletManager,
  WalletProvider,
} from '@txnlab/use-wallet-react'
import { WalletUIProvider } from '@txnlab/use-wallet-ui-react'

// Create and configure the wallet manager
const walletManager = new WalletManager({
  wallets: [
    // Add the wallets you want to support
    WalletId.PERA,
    WalletId.DEFLY,
    WalletId.LUTE,
    WalletId.EXODUS,
    // For WalletConnect, you'll need a project ID
    {
      id: WalletId.WALLETCONNECT,
      options: { projectId: 'your-project-id' },
    },
  ],
  defaultNetwork: NetworkId.TESTNET, // Or MAINNET for production
})

function App() {
  return (
    <WalletProvider manager={walletManager}>
      <WalletUIProvider>{/* Your app content */}</WalletUIProvider>
    </WalletProvider>
  )
}

The WalletProvider from @txnlab/use-wallet-react manages the wallet connections using the provided WalletManager configuration, while WalletUIProvider adds UI-specific features like NFD lookups and data prefetching.

2. Add the Wallet Button

The simplest way to enable wallet connectivity is with the WalletButton component:

import { WalletButton } from '@txnlab/use-wallet-ui-react'

function MyNav() {
  return (
    <nav>
      <WalletButton />
    </nav>
  )
}

The WalletButton is an all-in-one solution that:

  • Shows a connect button when disconnected
  • Opens the wallet selection dialog when clicked
  • Displays the connected wallet after connection
  • Shows NFD names and avatars when available
  • Provides access to account switching and disconnection

Component API

The library provides several components that can be used independently or together:

WalletUIProvider

Required wrapper that enables NFD lookups and data prefetching:

<WalletUIProvider
  // Optional configurations
  enablePrefetching={false} // Prefetch data for all accounts in a wallet (default: true)
  prefetchNfdView="brief" // Data view for NFD prefetching (default: 'thumbnail')
  queryClient={yourQueryClient} // Optional: integrate with existing Tanstack Query
>
  {/* Your app content */}
</WalletUIProvider>

WalletButton

All-in-one solution for wallet connectivity - combines the connect and connected states:

<WalletButton />

Connection Components

For more customization, use these component pairs:

Connect State (when disconnected)

import { ConnectWalletButton, ConnectWalletMenu } from '@txnlab/use-wallet-ui-react'

// Just the menu with default button:
<ConnectWalletMenu />

// Customized button:
<ConnectWalletMenu>
  <ConnectWalletButton className="bg-blue-500">
    Connect Wallet
  </ConnectWalletButton>
</ConnectWalletMenu>

// Fully custom trigger:
<ConnectWalletMenu>
  <button className="my-custom-button">Connect</button>
</ConnectWalletMenu>

Connected State (when wallet is connected)

import { ConnectedWalletButton, ConnectedWalletMenu } from '@txnlab/use-wallet-ui-react'

// Just the menu with default button:
<ConnectedWalletMenu />

// Customized button:
<ConnectedWalletMenu>
  <ConnectedWalletButton className="border-2 border-green-500" />
</ConnectedWalletMenu>

// Fully custom trigger:
<ConnectedWalletMenu>
  <div className="flex items-center gap-2">
    <span>My Wallet</span>
  </div>
</ConnectedWalletMenu>

NfdAvatar

Renders NFD avatars with automatic IPFS gateway handling:

import { useNfd, NfdAvatar } from '@txnlab/use-wallet-ui-react'

function Profile() {
  const nfdQuery = useNfd()

  return (
    <NfdAvatar
      nfd={nfdQuery.data}
      size={48}
      className="rounded-full border-2"
      alt="User profile"
    />
  )
}

NFD Integration

This library includes built-in support for NFD (Non-Fungible Domains) - Algorand's naming service that provides human-readable identities for wallet addresses.

The useNfd Hook

import { useNfd } from '@txnlab/use-wallet-ui-react'

function Profile() {
  // Gets NFD data for the currently connected address
  const nfdQuery = useNfd()

  if (nfdQuery.isLoading) return <div>Loading...</div>

  // Access NFD properties
  const name = nfdQuery.data?.name
  const userProperties = nfdQuery.data?.properties?.userDefined

  return (
    <div>
      <h2>{name || 'No NFD found'}</h2>
      <p>{userProperties?.bio || 'No bio'}</p>
    </div>
  )
}

NFD Features

  • Automatic lookup for the active wallet address
  • Support for different data views: 'tiny', 'thumbnail', 'brief', 'full'
  • Efficient caching via Tanstack Query
  • Works with both MainNet and TestNet
// Customizing the NFD lookup
const nfdQuery = useNfd({
  enabled: true, // Whether to enable the lookup
  view: 'brief', // Data view to request (default: 'thumbnail')
})

Account Information

Get account data like ALGO balance and asset holdings using the useAccountInfo hook:

import { useAccountInfo } from '@txnlab/use-wallet-ui-react'

function Balance() {
  // Gets account data for the connected address
  const accountQuery = useAccountInfo()

  if (accountQuery.isLoading) return <div>Loading...</div>
  if (!accountQuery.data) return <div>No account data</div>

  // Convert microAlgos to Algos (1 ALGO = 1,000,000 microAlgos)
  const algoBalance = Number(accountQuery.data.amount) / 1_000_000

  // Available balance (total minus minimum required)
  const minBalance = Number(accountQuery.data.minBalance) / 1_000_000
  const availableBalance = Math.max(0, algoBalance - minBalance)

  return (
    <div>
      <div>Total: {algoBalance.toFixed(2)} ALGO</div>
      <div>Available: {availableBalance.toFixed(2)} ALGO</div>
    </div>
  )
}

Advanced Customization

Styling Without Tailwind

When not using Tailwind, you have two options for customizing components:

1. Using the style prop

<ConnectWalletButton
  style={{
    backgroundColor: '#3366FF',
    color: 'white',
    fontWeight: 'bold',
  }}
>
  Connect
</ConnectWalletButton>

2. Using CSS selectors

First, add a custom class to the button:

<ConnectWalletButton className="connect-button">Connect</ConnectWalletButton>

Then target it in your CSS:

/* In your CSS */
[data-wallet-ui] .connect-button {
  font-family: 'Your Custom Font', sans-serif;
  background-color: #3366ff;
  color: white;
  padding: 8px 16px;
  border-radius: 4px;
  transition: background-color 0.2s;
}

[data-wallet-ui] .connect-button:hover {
  background-color: #2952cc;
}

Building Custom Wallet UI

For complete control, use the menu components with your own UI elements:

import { useWallet } from '@txnlab/use-wallet-react'
import {
  ConnectWalletMenu,
  ConnectedWalletMenu,
} from '@txnlab/use-wallet-ui-react'

function CustomWalletButton() {
  const { activeAddress } = useWallet()

  return activeAddress ? (
    <ConnectedWalletMenu>
      <YourCustomConnectedButton />
    </ConnectedWalletMenu>
  ) : (
    <ConnectWalletMenu>
      <YourCustomConnectButton />
    </ConnectWalletMenu>
  )
}

Integration with Tanstack Query

This library uses Tanstack Query internally for data fetching. If your application already uses Tanstack Query, you can integrate the two to avoid duplicate caches:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { WalletManager, WalletProvider } from '@txnlab/use-wallet-react'
import { WalletUIProvider } from '@txnlab/use-wallet-ui-react'

const queryClient = new QueryClient()
const walletManager = new WalletManager({...})

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <WalletProvider manager={walletManager}>
        <WalletUIProvider queryClient={queryClient}>
          {/* Your app */}
        </WalletUIProvider>
      </WalletProvider>
    </QueryClientProvider>
  )
}

By sharing the QueryClient, both your application and the wallet UI components will use the same query cache.

How It Works

The library follows a simple workflow:

  1. Disconnected State: WalletButton shows a connect button
  2. Connection Dialog: Clicking opens a dropdown with available Algorand wallets
  3. Connected State: After connecting, it displays the wallet address/NFD and balance
  4. Account Management: The dropdown provides options to switch accounts or disconnect

Behind the scenes, WalletUIProvider handles:

  • Prefetching NFD data for all accounts in the wallet
  • Converting IPFS URLs to HTTPS for avatars
  • Caching API responses for better performance
  • Handling network-specific behavior (MainNet/TestNet)

License

MIT