@avalabs/avacloud-kit-ui

AvaCloud UI Kit is a public React component library for AvaCloud apps. It combines scoped theming, chain-aware UI, AvaCloud-powered hooks, wallet connection flows, and an optional eERC entrypoint for encrypted token experiences.

What ships in the package

• Theme-aware UI primitives and crypto-focused components
• AvaCloud hooks for chains, balances, NFTs, and transaction history
• Wallet connection, connected-wallet, and network-gating flows
• A separate eerc entrypoint for encrypted ERC workflows

Install

Start with the package itself:

pnpm add @avalabs/avacloud-kit-ui

The current main entrypoint externalizes the provider, data, and wallet stack it uses internally. If your package manager reports missing peer dependencies, add the missing packages it asks for:

pnpm add react react-dom @tanstack/react-query @connectrpc/connect @connectrpc/connect-query wagmi viem

You do not need to import those libraries directly just to use the kit. They are peer dependencies because the current package surface depends on them under the hood.

Required app setup

1. Import the stylesheet once

The kit ships its own scoped stylesheet. Tailwind in the consumer app is optional.

@import '@avalabs/avacloud-kit-ui/styles.css';

If your app uses Tailwind, keep the kit stylesheet first:

@import '@avalabs/avacloud-kit-ui/styles.css';
@import 'tailwindcss';

2. Wrap the subtree with providers

ThemeProvider is required for kit styling and portaled UI. AvaCloudKitProvider is required for chain-aware, wallet-aware, and data-driven components.

import { useState } from 'react';
import {
  AvaCloudKitProvider,
  C_CHAIN_INFO_MAINNET,
  C_CHAIN_INFO_TESTNET,
  ChainSelect,
  ThemeProvider,
} from '@avalabs/avacloud-kit-ui';

export function Example() {
  const [selectedChainId, setSelectedChainId] = useState<string>();

  return (
    <ThemeProvider>
      <AvaCloudKitProvider
        value={{
          appName: 'My AvaCloud App',
          chains: [C_CHAIN_INFO_MAINNET, C_CHAIN_INFO_TESTNET],
        }}
      >
        <ChainSelect selectedChainId={selectedChainId} onSelect={setSelectedChainId} />
      </AvaCloudKitProvider>
    </ThemeProvider>
  );
}

Provider notes

• Pass queryClient if your app already owns a shared TanStack Query cache.
• Pass apiKey, authToken, or a custom transport when you need authenticated or customized AvaCloud requests.
• Set ssr: true and provide chains up front in SSR apps so wallet config does not hydrate against a temporary client-only chain list.
• Set walletConnectProjectId on AvaCloudKitProvider to enable WalletConnect in production.

Main entrypoint highlights

The main @avalabs/avacloud-kit-ui entrypoint includes:

• Inputs and identity: AddressChip, AddressInput, ChainSelect, Identicon, PaymentQRCode
• Tokens and activity: TokenSelector, TokenBalance, TokenAmountInput, NFTCard, NFTGallery, TransactionList
• Wallet UI: ConnectWalletButton, ConnectedWallet, ConnectedWalletGate, ConnectedNetworkGate
• Providers and hooks: ThemeProvider, AvaCloudKitProvider, useAvaCloudChains, useTokenBalances, useNftTokens, useTransactionHistory
• Helpers and constants: createAvaCloudKitTransport, addChainToWallet, C_CHAIN_INFO_MAINNET, C_CHAIN_INFO_TESTNET

Wallet flows

Wallet components need the AvaCloud provider plus the wallet-specific providers:

import {
  AvaCloudKitProvider,
  ConnectWalletButton,
  ConnectWalletProvider,
  SelectedWalletProvider,
  ThemeProvider,
} from '@avalabs/avacloud-kit-ui';

export function WalletExample() {
  return (
    <ThemeProvider>
      <AvaCloudKitProvider
        value={{
          appName: 'My AvaCloud App',
          walletConnectProjectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,
        }}
      >
        <SelectedWalletProvider>
          <ConnectWalletProvider appName="My AvaCloud App">
            <ConnectWalletButton />
          </ConnectWalletProvider>
        </SelectedWalletProvider>
      </AvaCloudKitProvider>
    </ThemeProvider>
  );
}

This gives you the connection dialog, connected-wallet surfaces, and connection/network gates. The wallet layer supports Core, MetaMask, Coinbase Wallet, WalletConnect, and optional additional flows such as Ledger.

eERC entrypoint

eERC features are intentionally split into a separate entrypoint so apps only opt in when they need encrypted balance or converter flows.

Install the extra peer only if you use eERC:

pnpm add @avalabs/eerc-sdk

Import the browser polyfills once before your app renders:

import '@avalabs/avacloud-kit-ui/eerc-polyfills';

Then import eERC APIs from the dedicated entrypoint:

import {
  EercBalance,
  EercGate,
  EercProvider,
  EercTransferForm,
} from '@avalabs/avacloud-kit-ui/eerc';

// Assumes ThemeProvider, AvaCloudKitProvider, SelectedWalletProvider,
// and ConnectWalletProvider are already mounted above this subtree.
export function PrivateTransfers() {
  return (
    <EercProvider contractAddress="0x...">
      <EercGate featureName="private transfers" withCard={false}>
        <EercBalance />
        <EercTransferForm />
      </EercGate>
    </EercProvider>
  );
}

eERC components assume the same wallet-enabled app shell used by the main package. The eerc entrypoint also exports converter forms, mint and burn flows, hooks, deployment helpers, and the default circuit URL helpers.

Entry points

| Import path | Use for | | --- | --- | | @avalabs/avacloud-kit-ui | Main component library, hooks, providers, helpers, and wallet flows | | @avalabs/avacloud-kit-ui/client | AvaCloud client helpers, transport creation, address utilities, and generated types | | @avalabs/avacloud-kit-ui/eerc | Encrypted ERC providers, hooks, forms, and deployment helpers | | @avalabs/avacloud-kit-ui/eerc-polyfills | Browser polyfills required by the eERC SDK | | @avalabs/avacloud-kit-ui/styles.css | Shared scoped stylesheet | | @avalabs/avacloud-kit-ui/tailwind.preset | Optional additive Tailwind preset |

Tailwind preset

If the host app uses Tailwind and you want AvaCloud token aliases in your own utilities, add the preset:

module.exports = {
  presets: [require('@avalabs/avacloud-kit-ui/tailwind.preset')],
};

The preset is additive. It does not replace the kit stylesheet.

Repository

• Source: https://github.com/ava-labs/avacloud-ui-kit
• Issues: https://github.com/ava-labs/avacloud-ui-kit/issues