Get Started
Install and configure Avail Widgets in your React project. Nexus Widget is the single unified component for all swap, send, and deposit flows.
Avail Widgets are shadcn-based components built on the Nexus SDK. Nexus Widget — the single unified component — handles swap, send, and deposit across chains.
Try Live Demo
Nexus Widget is the single unified component for all swap, send, and deposit flows. Choose your preferred install method:
Deposit (exact-output-mode)
Enter the exact amount to deposit; widget suggests and quotes tokens to spend.
Deposit (exact-input-mode)
Choose tokens and amounts to spend; widget quotes and deposits the received amount.
Swap and Bridge Widget
Swap and bridge assets across chains with the unified Nexus intent flow.
Send Widget
Send assets to any recipient on any chain with built-in progress tracking.
Try It Live
Install Nexus Widget
Install the package
pnpm add @avail-project/widgets
Peer dependencies:The package ships pre-compiled — no additional dependency installs or file copying required.viemandwagmiare required peer dependencies. Install them if you haven't already:pnpm add @avail-project/widgets viem wagmi @tanstack/react-query
Wrap your app with the provider
"use client";
import { NexusProvider } from "@avail-project/widgets";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<NexusProvider
config={{
network: "mainnet",
identity: { clientId: "YOUR_NEXUS_CLIENT_ID" },
}}
>
{children}
</NexusProvider>
);
}NexusProvider is mandatory — it creates the Nexus SDK client, exposes useNexus(), and every NexusWidget must be rendered inside it. See Client ID for what clientId is and how to get one.Initialize 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 "@avail-project/widgets";
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;
}Use the widget
import { NexusProvider, NexusWidget } from "@avail-project/widgets";
export function App({ address }: { address?: `0x${string}` }) {
return (
<NexusProvider
config={{
network: "mainnet",
identity: { clientId: "YOUR_NEXUS_CLIENT_ID" },
}}
>
<NexusWidget config={{ mode: "swap" }} connectedAddress={address} />
</NexusProvider>
);
}NexusProvider already wraps your app (as in the layout above), render NexusWidget anywhere beneath it and omit the extra provider.- Deposit (exact-output-mode):
config.mode = "deposit"(route: "exactOutput", default) — enter the exact amount you want to deposit. - Deposit (exact-input-mode):
config.mode = "deposit"(route: "exactInput") — choose one or more tokens to fund your deposit and review quoted returns. - Swap and Bridge:
config.mode = "swap"— swap and bridge assets through one unified intent flow. - Send:
config.mode = "send"— send assets to a recipient.
Client ID
clientId identifies your app (not an end user or wallet) to Nexus. Set it once on NexusProvider:
<NexusProvider
config={{
network: "mainnet",
identity: { clientId: "YOUR_NEXUS_CLIENT_ID" },
}}
>
{children}
</NexusProvider>Treat clientId as required
If you omit it,
NexusProvider falls back to your site's hostname (for example example.com, or localhost for local and non-browser environments). Widgets still work, but the fallback is not a stable identity, and widget telemetry is only recorded when you pass an explicit identity.clientId. Always set it in production.- One stable ID per integrating app. Reuse the same value across environments and deployments of that app.
- Getting an ID. Client IDs are currently allocated by the Nexus team — reach out to Avail to get one for your app. Don't ship the
YOUR_NEXUS_CLIENT_IDplaceholder. - Both install methods. The npm package and the shadcn component accept the same
config.identityshape. - Opting out. To disable widget telemetry, set
observability: { disableLogging: true }in the provider config.
How is this guide?