Nexus Elements - NexusProvider

Overview

Install NexusProvider, initialize the SDK once on wallet connect, and access Nexus context via useNexus. All Nexus Elements widgets depend on this provider.

What NexusProvider does

• Creates a single NexusSDK instance (configurable network and debug).
• Initializes the SDK with an EIP-1193 provider (handleInit).
• Preloads:
  • supported chains/tokens (bridge + swap)
  • bridgeable and swappable balances
  • exchange rates (Coinbase) for fiat display
• Attaches SDK hooks for intent, allowance, and swap intent previews.
• Exposes all of the above to components via useNexus().

Install (shadcn registry)

1. Ensure shadcn/ui is initialized (components.json exists).
2. Ensure registry mapping exists:

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

3. Install:

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

Alternative:

npx shadcn@latest add https://elements.nexus.availproject.org/r/nexus-provider.json

Manual install (no shadcn)

1. Download https://elements.nexus.availproject.org/r/nexus-provider.json.
2. Create each file in files[].target with files[].content.
3. Install dependencies: @avail-project/nexus-core@1.0.0-beta.64 and wagmi.

Usage

Wrap your app:

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

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <NexusProvider>{children}</NexusProvider>;
}

Initialize on wallet connect (wagmi example):

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

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

  useEffect(() => {
    if (status === "connected") {
      connector?.getProvider().then((p) => handleInit(p as EthereumProvider));
    }
  }, [status, connector, handleInit]);

  return null;
}

What useNexus() provides

• nexusSDK: initialized SDK instance (or null before init)
• handleInit(provider): init + preload + attach hooks
• initializeNexus(provider) / deinitializeNexus(): manual lifecycle control
• intent, allowance, swapIntent: refs for SDK hooks (must call allow()/deny())
• supportedChainsAndTokens, swapSupportedChainsAndTokens
• bridgableBalance, swapBalance
• exchangeRate, getFiatValue(amount, symbol)
• fetchBridgableBalance(), fetchSwapBalance()
• loading, network

Notes

• handleInit expects an EIP-1193 provider with request().
• Optional config supports network ("mainnet"/"testnet" or custom) and debug.
• Hooks are attached in handleInit; if you override hooks elsewhere, always call allow()/deny() or flows will stall.
• Provider auto-deinitializes on wallet disconnect via wagmi useAccountEffect; if not using wagmi, call deinitializeNexus() manually.