Your First Widget

Render the Nexus Widget and understand how props and callbacks work.

You have installed the component and configured the NexusProvider. Now it is time to render a working widget. In this guide you will add Nexus Widget to a page, understand each prop it accepts, and handle its lifecycle callbacks.

What you will build

By the end of this page you will have a fully functional swap-and-bridge widget embedded in your app. The user will be able to select a source and receive asset across chains and execute the intent — all with built-in progress UI, fee breakdowns, and error handling. Switching to send or deposit is a one-line config.mode change.

Interactive Configurator

You can generate the exact basic config for your desired widget mode live using the Widget Configurator .

Step 1 — Install the package

If you have not already installed the package during the installation step, install it now:


pnpm add @avail-project/widgets

Step 2 — Create a page

Create a new page (or add to an existing one) that renders NexusWidget. Here is a complete example:

app/swap/page.tsx

"use client";
import { useAccount } from "wagmi";
import { NexusWidget } from "@avail-project/widgets";
 
const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 
export default function SwapPage() {
  const { address } = useAccount();
 
  if (!address) {
    return <p>Connect your wallet to get started.</p>;
  }
 
  return (
    <div className="mx-auto max-w-md py-12">
      <NexusWidget
        connectedAddress={address}
        config={{
          mode: "swap",
          destination: {
            chain: 8453,
            tokens: [{ address: USDC_BASE, symbol: "USDC", decimals: 6 }],
          },
        }}
        onStart={() => console.log("Intent started")}
        onComplete={(explorerUrl) => console.log("Complete!", explorerUrl)}
        onError={(message) => console.error("Error:", message)}
      />
    </div>
  );
}

Step 3 — Understand the props

Here is a breakdown of the props NexusWidget accepts and what they control:

Prop	Type	Required	Description
`config`	`NexusWidgetConfig`	Yes	Selects the workflow with `config.mode` (`"swap"`, `"send"`, or `"deposit"`) and any mode-specific behavior.
`config.mode`	`"swap" \| "send" \| "deposit"`	Yes	The flow to render.
`config.destination`	`{ chain?, tokens? }`	Conditional	Required for deposit. Optional for send/swap; when supplied, it restricts the destination chain/token selection.
`config.prefill`	`object`	No	Pre-populate the form (amount for deposit/send, initial token for send/swap) so the user acts with fewer clicks.
`config.appearance`	`object`	No	Branding overrides: `heading`, `appName`, `appLogoURL`, `primaryColor`, and `mode` (`"system"`, `"light"`, `"dark"`).
`connectedAddress`	`0x${string}`	No	Wallet address to use. If omitted, the connected wagmi account is used.
`embed`	`boolean`	No	Defaults to `true`. Set `false` to render as a modal surface, controlled with `open`, `onOpenChange`, and `defaultOpen`.
`onComplete`	`(explorerUrl?: string) => void`	No	Called after a successful swap, send, or deposit. Use it to refresh balances or navigate.
`onStart`	`() => void`	No	Called when the user starts execution. Useful for analytics.
`onError`	`(message: string) => void`	No	Called if execution fails, with a human-readable message.
`onClose`	`() => void`	No	Used by modal mode. The close button is hidden in embedded mode.
`onConnectClick`	`() => void \| Promise<void>`	No	Called when the widget's internal Connect Wallet CTA is clicked. Use it to open your app's wallet modal.

config.mode is the only always-required field

Beyond config.mode, every field is optional unless the selected mode makes it conditional (deposit requires destination, depositAddress, and executeDeposit). See the Swap and Bridge, Send, and Deposit pages for each mode's configuration reference.

Step 4 — Run and test

Start your development server and navigate to the page:


pnpm dev

Open your app in the browser
Connect a wallet using your wallet connection UI
The widget should appear with USDC on Base pre-selected as the receive asset
Try selecting a different token or chain to verify the form is interactive

Mainnet only

Nexus Widget currently supports mainnet only. Testnet is not supported at the moment.

Switching modes

The same component powers send and deposit — just change config.mode. To render a send flow instead:

<NexusWidget
  connectedAddress={address}
  config={{
    mode: "send",
    destination: {
      chain: 8453,
      tokens: [
        {
          address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          symbol: "USDC",
          decimals: 6,
        },
      ],
    },
    prefill: { amount: "0.1" },
  }}
  onComplete={() => console.log("Send complete")}
/>

What's next

You now have a working Nexus Widget integration. From here you can explore each mode:

Swap and Bridge

Swap and bridge assets with the unified Nexus intent flow.

Send

Route funds to a recipient with Nexus intents.

Deposit

Route funds into a configured protocol or app action with Nexus intents.

How is this guide?

NexusProvider Setup

Swap and Bridge

What you will build Interactive Configurator Step 1 — Install the package Step 2 — Create a page Step 3 — Understand the props Step 4 — Run and test Switching modes What's next

Edit in GitHub

"use client"; import { useAccount } from "wagmi"; import { NexusWidget } from "@avail-project/widgets"; const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; export default function SwapPage() { const { address } = useAccount(); if (!address) { return <p>Connect your wallet to get started.</p>; } return ( <div className="mx-auto max-w-md py-12"> <NexusWidget connectedAddress={address} config={{ mode: "swap", destination: { chain: 8453, tokens: [{ address: USDC_BASE, symbol: "USDC", decimals: 6 }], }, }} onStart={() => console.log("Intent started")} onComplete={(explorerUrl) => console.log("Complete!", explorerUrl)} onError={(message) => console.error("Error:", message)} /> </div> ); }

Prop

Type

Required

Description

config

NexusWidgetConfig

Yes

Selects the workflow with config.mode ("swap", "send", or "deposit") and any mode-specific behavior.

config.mode

"swap" | "send" | "deposit"

Yes

The flow to render.

config.destination

{ chain?, tokens? }

Conditional

Required for deposit. Optional for send/swap; when supplied, it restricts the destination chain/token selection.

config.prefill

object

Pre-populate the form (amount for deposit/send, initial token for send/swap) so the user acts with fewer clicks.

config.appearance

object

Branding overrides: heading, appName, appLogoURL, primaryColor, and mode ("system", "light", "dark").

connectedAddress

`0x${string}`

Wallet address to use. If omitted, the connected wagmi account is used.

embed

boolean

Defaults to true. Set false to render as a modal surface, controlled with open, onOpenChange, and defaultOpen.

onComplete

(explorerUrl?: string) => void

Called after a successful swap, send, or deposit. Use it to refresh balances or navigate.

onStart

() => void

Called when the user starts execution. Useful for analytics.

onError

(message: string) => void

Called if execution fails, with a human-readable message.

onClose

() => void

Used by modal mode. The close button is hidden in embedded mode.

onConnectClick

() => void | Promise<void>

Called when the widget's internal Connect Wallet CTA is clicked. Use it to open your app's wallet modal.

<NexusWidget connectedAddress={address} config={{ mode: "send", destination: { chain: 8453, tokens: [ { address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", symbol: "USDC", decimals: 6, }, ], }, prefill: { amount: "0.1" }, }} onComplete={() => console.log("Send complete")} />

Search Documentation

Your First Widget

What you will build

Interactive Configurator

Step 1 — Install the package

Step 2 — Create a page

Step 3 — Understand the props

Step 4 — Run and test

Switching modes

What's next

Search Documentation

Your First Widget

What you will build

Interactive Configurator

Step 1 — Install the package

Step 2 — Create a page

Step 3 — Understand the props

Step 4 — Run and test

Switching modes

What's next