> ## Documentation Index
> Fetch the complete documentation index at: https://spiceflow-docs.spicenet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Components

> Complete reference for all Spice Flow SDK components

## SpiceFlowProvider

The root provider that wraps your application. Manages wallet connections, chain configuration, theming, and execution mode.

### Usage

```tsx theme={null}
import { SpiceFlowProvider } from "@spicenet-io/spiceflow-ui";

<SpiceFlowProvider
  provider="privy"
  network="mainnet"
  nativeChainId={8453}
  theme={{ primaryColor: "#f97316", dark: true }}
>
  {children}
</SpiceFlowProvider>
```

### Props

| Prop                   | Type                                | Required   | Default      | Description                                             |
| ---------------------- | ----------------------------------- | ---------- | ------------ | ------------------------------------------------------- |
| `provider`             | `"privy" \| "dynamic"`              | Yes        |              | Wallet provider to use                                  |
| `children`             | `ReactNode`                         | Yes        |              | Your application components                             |
| `network`              | `"mainnet" \| "testnet"`            | No         | `"testnet"`  | Network environment                                     |
| `nativeChainId`        | `number`                            | No         |              | Default chain for the user                              |
| `brand`                | `SpiceBrand`                        | No         |              | Branding and theme config (see [Styling](/sdk/styling)) |
| `privyAppId`           | `string`                            | If Privy   |              | Privy application ID                                    |
| `dynamicEnvironmentId` | `string`                            | If Dynamic |              | Dynamic environment ID                                  |
| `supportedChainIds`    | `number[]`                          | No         | Per network  | Override supported chain IDs                            |
| `mode`                 | `"7702" \| "presign" \| "ondemand"` | No         | `"7702"`     | Execution mode                                          |
| `appName`              | `string`                            | No         | `"Spicenet"` | Your application name                                   |
| `apiUrl`               | `string`                            | No         |              | Override relayer API URL                                |
| `embeddedWalletConfig` | `object`                            | No         |              | Embedded wallet configuration                           |

### Examples

<CodeGroup>
  ```tsx Privy (Mainnet) theme={null}
  <SpiceFlowProvider
    provider="privy"
    network="mainnet"
    nativeChainId={8453}
    theme={{ primaryColor: "#f97316", dark: true }}
  >
    {children}
  </SpiceFlowProvider>
  ```

  ```tsx Dynamic theme={null}
  <SpiceFlowProvider
    provider="dynamic"
    dynamicEnvironmentId="your-dynamic-env-id"
    network="mainnet"
    nativeChainId={8453}
  >
    {children}
  </SpiceFlowProvider>
  ```

  ```tsx Non 7702 Mode (Pharos) theme={null}
  <SpiceFlowProvider
    provider="privy"
    mode="ondemand"
    network="mainnet"
    nativeChainId={688689}
  >
    {children}
  </SpiceFlowProvider>
  ```
</CodeGroup>

***

## SpiceDeposit

The main deposit flow. Handles everything: Privy login, external wallet connection, token selection, escrow deposit, 7702 signing, and solver execution. This is the primary component most apps will use.

### Usage

```tsx theme={null}
import { SpiceDeposit } from "@spicenet-io/spiceflow-ui";

<SpiceDeposit
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  depositBatches={batches}
  styles={{ primaryColor: "#f97316" }}
/>
```

### Props

| Prop                      | Type                                                         | Required | Default | Description                                                     |
| ------------------------- | ------------------------------------------------------------ | -------- | ------- | --------------------------------------------------------------- |
| `isOpen`                  | `boolean`                                                    | Yes      |         | Control modal visibility                                        |
| `onClose`                 | `() => void`                                                 | Yes      |         | Close handler                                                   |
| `styles`                  | `CustomStyles`                                               | No       |         | Custom styling                                                  |
| `depositBatches`          | `ChainBatch[] \| ((amount, token) => Promise<ChainBatch[]>)` | No       |         | Destination chain calls to execute after deposit                |
| `allowedTokens`           | `string[]`                                                   | No       |         | Filter token list by symbol (lowercase), e.g. `["usdc", "eth"]` |
| `onDepositAmountChange`   | `(amount: string) => void`                                   | No       |         | Fires when user changes the deposit amount                      |
| `destinationChainId`      | `number`                                                     | No       |         | Target chain for execution                                      |
| `destinationTokenAddress` | `string`                                                     | No       |         | Target token on destination chain                               |
| `onDepositExecute`        | `(amount: string) => Promise<void>`                          | No       |         | Callback for non 7702 mode (app handles execution)              |
| `depositActionLabel`      | `string`                                                     | No       |         | Custom label for the action button                              |
| `airdrop`                 | `boolean`                                                    | No       | `false` | Show testnet airdrop button                                     |
| `sponsorGas`              | `boolean`                                                    | No       | `false` | Backend sponsors gas                                            |
| `skipTokenSelection`      | `boolean`                                                    | No       | `false` | Skip the token selection step                                   |
| `skipRecovery`            | `boolean`                                                    | No       | `false` | Skip the stranded funds recovery prompt                         |
| `escrowRecovery`          | `EscrowRecovery`                                             | No       |         | Recover funds stuck in escrow                                   |
| `onDepositSuccess`        | `(detail) => void`                                           | No       |         | Success callback with tx details                                |

### depositBatches

The `depositBatches` prop defines what happens on the destination chain after the deposit. It can be a static array or an async function that returns batches based on the deposit amount:

```tsx theme={null}
// Static batches
const batches = [
  {
    chainId: 8453,
    calls: [
      { to: TOKEN, value: 0n, data: encodeApprove(VAULT, amount) },
      { to: VAULT, value: 0n, data: encodeDeposit(TOKEN, amount) },
    ],
  },
];

// Dynamic batches (computed from deposit amount)
const dynamicBatches = async (amount: string, tokenAddress: string) => {
  const parsedAmount = parseUnits(amount, 6);
  return [
    {
      chainId: 8453,
      calls: [
        { to: tokenAddress, value: 0n, data: encodeApprove(VAULT, parsedAmount) },
        { to: VAULT, value: 0n, data: encodeDeposit(tokenAddress, parsedAmount) },
      ],
    },
  ];
};
```

***

## SpiceWithdraw

Withdraw assets from the user's Spice balance back to their wallet. Users select from their deposited tokens and receive the same token on the same chain.

### Usage

```tsx theme={null}
import { SpiceWithdraw } from "@spicenet-io/spiceflow-ui";

<SpiceWithdraw
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  styles={{ primaryColor: "#f97316" }}
/>
```

### Props

| Prop                  | Type                                | Required | Default | Description                |
| --------------------- | ----------------------------------- | -------- | ------- | -------------------------- |
| `isOpen`              | `boolean`                           | Yes      |         | Control modal visibility   |
| `onClose`             | `() => void`                        | Yes      |         | Close handler              |
| `styles`              | `CustomStyles`                      | No       |         | Custom styling             |
| `onWithdrawExecute`   | `(amount: string) => Promise<void>` | No       |         | Callback for non 7702 mode |
| `withdrawActionLabel` | `string`                            | No       |         | Custom button label        |
| `onWithdrawSuccess`   | `(data) => void`                    | No       |         | Success callback           |
| `onWithdrawError`     | `(error: string) => void`           | No       |         | Error callback             |
| `supportedChains`     | `number[]`                          | No       |         | Filter to specific chains  |

***

## SpiceLockModal

Lock tokens for a duration (veToken style). Supports cross chain deposits into the lock. The app provides duration options and the lock batches.

### Usage

```tsx theme={null}
import { SpiceLockModal } from "@spicenet-io/spiceflow-ui";

<SpiceLockModal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  lockBatches={lockBatches}
  lockTokenSymbol="veREPPO"
  lockChainId={4114}
  sourceChains={[8453, 42161, 4114]}
  durationOptions={[
    { label: "1 Month", months: 1 },
    { label: "3 Months", months: 3 },
    { label: "6 Months", months: 6 },
    { label: "12 Months", months: 12 },
  ]}
  styles={{ primaryColor: "#f97316" }}
/>
```

### Props

| Prop                                | Type                         | Required | Default | Description                                    |
| ----------------------------------- | ---------------------------- | -------- | ------- | ---------------------------------------------- |
| `isOpen`                            | `boolean`                    | Yes      |         | Modal visibility                               |
| `onClose`                           | `() => void`                 | Yes      |         | Close handler                                  |
| `lockBatches`                       | `ChainBatch[]`               | Yes      |         | On chain lock calls                            |
| `lockTokenSymbol`                   | `string`                     | Yes      |         | Display symbol for the lock token              |
| `lockChainId`                       | `number`                     | Yes      |         | Chain where the lock contract lives            |
| `sourceChains`                      | `number[]`                   | Yes      |         | Chains users can deposit from                  |
| `durationOptions`                   | `LockDurationOption[]`       | Yes      |         | Available lock durations                       |
| `styles`                            | `CustomStyles`               | No       |         | Custom styling                                 |
| `dark`                              | `boolean`                    | No       |         | Dark mode override                             |
| `lockTokenLogoURI`                  | `string`                     | No       |         | Logo URL for the lock token                    |
| `votingPowerEstimate`               | `(amount, months) => number` | No       |         | Estimate voting power from amount and duration |
| `sourceToDestinationConversionRate` | `number`                     | No       |         | Conversion rate display                        |
| `onLockSuccess`                     | `(txHash?: string) => void`  | No       |         | Success callback                               |
| `onAddFunds`                        | `() => void`                 | No       |         | Handler for "add funds" action                 |
| `destinationTokenAddress`           | `Address`                    | No       |         | Target token on lock chain                     |

***

## AccountDisplay

A popover that shows the user's Spice balance breakdown, pending deposits, and quick actions for deposit/withdraw. Great for header navigation.

### Usage

```tsx theme={null}
import { AccountDisplay } from "@spicenet-io/spiceflow-ui";

<AccountDisplay
  styles={{ primaryColor: "#f97316" }}
  onDepositClick={() => setDepositOpen(true)}
  onWithdrawClick={() => setWithdrawOpen(true)}
/>
```

### Props

| Prop               | Type                     | Required | Default    | Description                        |
| ------------------ | ------------------------ | -------- | ---------- | ---------------------------------- |
| `styles`           | `CustomStyles`           | No       |            | Custom styling                     |
| `dark`             | `boolean`                | No       |            | Dark mode override                 |
| `appName`          | `string`                 | No       | `"Spice"`  | Display name                       |
| `status`           | `"active" \| "inactive"` | No       | `"active"` | Account status indicator           |
| `statusLabel`      | `string`                 | No       |            | Custom status text                 |
| `onDepositClick`   | `() => void`             | No       |            | Deposit button handler             |
| `onWithdrawClick`  | `() => void`             | No       |            | Withdraw button handler            |
| `onDepositSuccess` | `() => void`             | No       |            | Called after successful deposit    |
| `customSections`   | `CustomSection[]`        | No       |            | Add custom sections to the popover |
| `extraAssets`      | `SpiceAsset[]`           | No       |            | Additional assets to display       |
| `tokenPrices`      | `Record<string, number>` | No       |            | Token price overrides              |
| `supportedChains`  | `number[]`               | No       |            | Filter chains shown                |

***

## SpiceBalance

A balance dashboard card that shows the user's deposited assets. Usually used within a larger page layout rather than as a standalone modal.

### Usage

```tsx theme={null}
import { SpiceBalance, useSpiceAssets } from "@spicenet-io/spiceflow-ui";

function Dashboard() {
  const { assets, loading } = useSpiceAssets({ address: userAddress });

  return (
    <SpiceBalance
      balanceData={balanceData}
      isLoading={loading}
      onDepositClick={() => setDepositOpen(true)}
      onWithdrawClick={() => setWithdrawOpen(true)}
    />
  );
}
```

### Props

| Prop              | Type                     | Required | Default | Description             |
| ----------------- | ------------------------ | -------- | ------- | ----------------------- |
| `balanceData`     | `BalanceData`            | Yes      |         | Balance data object     |
| `isLoading`       | `boolean`                | No       | `false` | Loading state           |
| `onDepositClick`  | `() => void`             | No       |         | Deposit button handler  |
| `onWithdrawClick` | `() => void`             | No       |         | Withdraw button handler |
| `styles`          | `CustomStyles`           | No       |         | Custom styling          |
| `showHeader`      | `boolean`                | No       | `true`  | Show the header         |
| `customSections`  | `BalanceSectionConfig[]` | No       |         | Custom balance sections |

***

## AirdropModal

Request testnet tokens for development and testing.

### Usage

```tsx theme={null}
import { AirdropModal } from "@spicenet-io/spiceflow-ui";

<AirdropModal
  isOpen={isOpen}
  onClose={() => setIsOpen(false)}
  chainId={5115}
  walletAddress={address}
  airdropTokens={["USDC", "WBTC"]}
  getChainConfig={getChainConfig}
  getSupportedTokens={getSupportedTokens}
/>
```

***

## ProviderLogin

Wallet connection button that adapts to your selected provider (Privy or Dynamic).

### Usage

```tsx theme={null}
import { ProviderLogin } from "@spicenet-io/spiceflow-ui";

<ProviderLogin onAuthSuccess={() => console.log("Logged in")} />
```

### Props

| Prop            | Type         | Required | Description                              |
| --------------- | ------------ | -------- | ---------------------------------------- |
| `onAuthSuccess` | `() => void` | No       | Callback after successful authentication |
| `autoTrigger`   | `boolean`    | No       | Automatically trigger login on mount     |

***

## ExportWalletButton

Lets users export their Privy embedded wallet private key.

```tsx theme={null}
import { ExportWalletButton } from "@spicenet-io/spiceflow-ui";

<ExportWalletButton />
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Hooks" icon="code" href="/sdk/hooks">
    Build custom UIs with React hooks
  </Card>

  <Card title="Styling" icon="palette" href="/sdk/styling">
    Customize component appearance
  </Card>

  <Card title="Configuration" icon="sliders" href="/sdk/configuration">
    Configure chains and providers
  </Card>

  <Card title="Examples" icon="book" href="/guides/native-swap">
    See complete examples
  </Card>
</CardGroup>