SpiceFlow UI SDK

A React component library for building DeFi swap interfaces with multi-chain support.

Installation

npm install @spicenet-io/spiceflow-ui

Usage

import { SwapWidget, SpiceFlowProvider } from "@spicenet-io/spiceflow-ui";
import "@spicenet-io/spiceflow-ui/styles.css";

function App() {
  return (
    <SpiceFlowProvider
      provider="privy"
      privyAppId="your-privy-app-id"
      dynamicEnvironmentId="your-env-id"
      paraApiKey="your-para-api-key"
      paraAppName="your-app-name"
    >
      <SwapWidget
        swapBatches={swapBatches}
        supportedChains={[1, 137, 42161]}
        showSlippageSettings={true}
        enableFlipSwap={true}
        theme="dark"
      />
    </SpiceFlowProvider>
  );
}

Components

• SwapWidget - Main swap interface component
• AssetSelector - Token selection component
• SpiceDeposit - Deposit modal component
• StatusDisplay - Transaction status display
• ProviderLogin - Wallet connection component
• DebugWidget - Development debugging component
• Button, Input, Modal - UI primitives

Development

Fee-Charging Intent Flows

• SpiceSupply and SpicePay are fee-charging intent-execution flows and must surface fee estimation before enabling submission.
• SpiceLockModal is also a fee-charging intent-execution flow and must surface fee estimation before enabling submission.
• SpiceDeposit and SpiceWithdraw are treated as non-fee actions and should not use the fee-estimation gating UX.
• Rule of thumb: every intent-execution flow other than deposit/withdraw should assume fees apply and should gate CTA enablement on successful fee estimation.

Building the Library

bun run build

Type Checking

bun run typecheck

Linting

bun run lint
bun run lint:fix

Component Playground

This repository includes a lightweight React playground app for viewing and testing all components without the complexity of Storybook.

Running the Playground

1. Install dependencies (if not already done):

   bun install --frozen-lockfile

2. Navigate to the playground directory:

   cd playground

3. Install playground dependencies:

   bun install --frozen-lockfile

4. Start the development server:

   bun run dev

   The playground will open automatically at http://localhost:3000

Using the Playground

• Left Sidebar: Browse available components
• Main Area: View the selected component with different example variants
• Example Tabs: Switch between different states/examples for each component

Adding a New Component Example

To add a new example variant for a component:

1. Open playground/src/ComponentRegistry.tsx
2. Find the component's entry in the examples object
3. Add a new entry to the array:

   {
     label: 'Your Example Name',
     render: () => <YourComponent {...props} />,
   }

The playground will automatically pick up the new example and display it as a tab.

License

MIT