Setup

Go from install to first widget

This guide covers the minimum app shell for AvaCloud UI Kit and the few places where integration details matter: stylesheet order, provider boundaries, and shared query/cache wiring.

Required providersScoped stylesProduction-friendly defaults

Required wrappers

ThemeProvider + AvaCloudKitProvider

ThemeProvider scopes tokens; AvaCloudKitProvider supplies chains, transport, and hooks.

Tailwind dependency

Not required

Import the kit stylesheet and the components will render correctly without Tailwind in the consumer app.

Shared cache

Optional

Bring your own QueryClient if the app already uses TanStack Query.

Provider order matters

ThemeProvider must wrap the subtree that renders AvaCloud Kit components, and AvaCloudKitProvider should live inside it so portaled surfaces inherit the same token scope.

Install the package

pnpm add @avalabs/avacloud-kit-ui-preview

If your app already uses wagmi or TanStack Query, the kit integrates cleanly with those existing instances.

Add the stylesheet once

app/globals.css

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

app/globals.css

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

Keep the kit stylesheet first. It provides the scoped utility classes used internally by the components.

Recommended app structure

globals.css

providers.tsx

page.tsx

Wrap the app shell

Create a shared provider module so your component tree always has access to theme tokens and AvaCloud context.

Pass chains directly if you want deterministic wallet behavior during SSR.

Reuse your existing QueryClient when the host app already has one.

app/providers.tsx

import type { ReactNode } from 'react';
import {
  AvaCloudKitProvider,
  C_CHAIN_INFO_MAINNET,
  C_CHAIN_INFO_TESTNET,
  ThemeProvider,
} from '@avalabs/avacloud-kit-ui-preview';

export function AppProviders({ children }: { children: ReactNode }) {
  return (
    <ThemeProvider>
      <AvaCloudKitProvider
        value={{
          chains: [C_CHAIN_INFO_MAINNET, C_CHAIN_INFO_TESTNET],
        }}
      >
        {children}
      </AvaCloudKitProvider>
    </ThemeProvider>
  );
}

app/providers.tsx

import { QueryClient } from '@tanstack/react-query';
import { useMemo, type ReactNode } from 'react';
import { AvaCloudKitProvider, ThemeProvider } from '@avalabs/avacloud-kit-ui-preview';

export function AppProviders({ children }: { children: ReactNode }) {
  const queryClient = useMemo(() => new QueryClient(), []);

  return (
    <ThemeProvider>
      <AvaCloudKitProvider
        value={{
          apiKey: process.env.NEXT_PUBLIC_AVACLOUD_API_KEY,
          queryClient,
        }}
      >
        {children}
      </AvaCloudKitProvider>
    </ThemeProvider>
  );
}

Render your first component

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

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

  return (
    <ChainSelect
      selectedChainId={selectedChainId}
      onSelect={setSelectedChainId}
      chainIds={[C_CHAIN_INFO_MAINNET.vmInfo.evmChainId, C_CHAIN_INFO_TESTNET.vmInfo.evmChainId]}
    />
  );
}

Pull chain data into your own UI

import { useAvaCloudChains } from '@avalabs/avacloud-kit-ui-preview';

export function ChainList() {
  const { data, isLoading } = useAvaCloudChains();

  if (isLoading || !data) return <div>Loading chains…</div>;

  return (
    <ul>
      {data.map((chain) => (
        <li key={chain.chainId}>{chain.name}</li>
      ))}
    </ul>
  );
}

Go from install to first widget

Install the package

Add the stylesheet once

Recommended app structure

Wrap the app shell

Render your first component

Pull chain data into your own UI

Continue with styling and components

Theme the subtree

Browse the component catalog

On this page