availproject/nexus-elements-overview

Nexus Elements Overview

Nexus One is the only element you need

All legacy standalone widgets have been deprecated and removed. Nexus One is the single unified component that handles swap, send (transfer), and deposit flows.

| Legacy element | Status | Nexus One replacement | |---|---|---| | FastBridge | ❌ Removed | NexusOne with config.mode = "swap" | | FastTransfer | ❌ Removed | NexusOne with config.mode = "send" | | SwapWidget | ❌ Removed | NexusOne with config.mode = "swap" | | Deposit | ❌ Removed | NexusOne with config.mode = "deposit" + opportunities | | BridgeDeposit | ❌ Removed | NexusOne with config.mode = "deposit" + opportunities | | UnifiedBalance | ❌ Removed | Inline balance view in Nexus One | | ViewHistory | ❌ Removed | Use sdk.getMyIntents() directly |

Install Nexus One

npx shadcn@latest add @nexus-elements/nexus-one

Integrate end-to-end in any TS/React app

1. Install project deps

pnpm add @avail-project/nexus-core wagmi viem lucide-react @tanstack/react-query

2. Configure registry

Add this mapping in components.json:

"registries": {
  "@nexus-elements/": "https://elements.nexus.availproject.org/r/{name}.json"
}

3. Set up NexusProvider

Install and wire nexus-provider before Nexus One:

npx shadcn@latest add @nexus-elements/nexus-provider

Wrap your app with NexusProvider:

"use client";

import NexusProvider from "@/components/nexus/NexusProvider";

export function AppNexusProvider({ children }: { children: React.ReactNode }) {
  return <NexusProvider config={{ network: "mainnet" }}>{children}</NexusProvider>;
}

4. Initialize SDK on wallet connect

"use client";

import { useEffect } from "react";
import { useAccount, useConnectorClient } from "wagmi";
import type { EthereumProvider } from "@avail-project/nexus-core";
import { useNexus } from "@/components/nexus/NexusProvider";

export function InitNexusOnConnect() {
  const { status, connector } = useAccount();
  const { data: walletClient } = useConnectorClient();
  const { handleInit } = useNexus();

  useEffect(() => {
    if (status !== "connected") return;

    void (async () => {
      const mobileProvider = walletClient
        ? ({ request: (args: unknown) => walletClient.request(args as never) } as EthereumProvider)
        : undefined;
      const desktopProvider = await connector?.getProvider();
      const provider = mobileProvider ?? (desktopProvider as EthereumProvider | undefined);
      if (!provider || typeof provider.request !== "function") return;
      await handleInit(provider);
    })();
  }, [status, connector, walletClient, handleInit]);

  return null;
}

5. Render Nexus One

import { NexusOne } from "@/components/nexus-one/nexus-one";

// Swap mode (also handles bridges)
<NexusOne config={{ mode: "swap" }} connectedAddress={address} />

// Send mode
<NexusOne config={{ mode: "send" }} connectedAddress={address} />

// Deposit mode
<NexusOne
  config={{
    mode: "deposit",
    opportunities: [{ /* ... */ }],
  }}
  connectedAddress={address}
/>

Nexus SDK agent skills

For detailed SDK integration guidance, use the Nexus SDK agent skills (.agents/skills/):

• nexus-sdk-setup — SDK initialization and wallet wiring
• nexus-sdk-bridge-flows — bridge, bridgeAndTransfer, bridgeAndExecute
• nexus-sdk-swap-flows — swapWithExactIn, swapWithExactOut, swapAndExecute
• nexus-sdk-hooks-events — intent hooks and event streaming
• nexus-sdk-balances-metadata-utils — balances, supported chains/tokens, formatters
• nexus-sdk-integration — end-to-end integration guide

E2E readiness checklist

• Confirm wallet connects and handleInit runs once per session.
• Confirm useNexus().nexusSDK is non-null after connect.
• Confirm Nexus One renders and responds to mode/prefill config.
• Confirm every flow (swap, send, deposit) can reach success.
• Confirm disconnect clears SDK state (deinitializeNexus).

Common integration failures

• Invalid provider object:
  • Ensure provider has request().
• Nexus One not rendering:
  • Ensure NexusProvider wraps your app and SDK is initialized.
• Empty balance/sources:
  • Ensure SDK init finished and wallet is connected on a supported network.