Follow for latest

Twitter @gizmolab_

Getting started

IntroductionInstall Abstract Global WalletInstall Next.js 14Install DynamicInstall Shadcn UiDeploy EVM Contract

All Components

Abstract Gasless NFT Mint ComponentAbstract Sign InChain SelectorCrypto Product CardNft Mint CardNFT Portfolio DashboardLiFi WidgetPolymarket Widget Component
LiFi widget preview

LI.FI Widget React Integration Guide

Add the LI.FI widget to a React or Next.js app, ship swap and bridge UX faster, and tighten the experience around your product rules instead of building every cross-chain detail from scratch.

The existing LiFi Widget component page already captures interest from teams evaluating a cross-chain embed. This guide sharpens that intent into a React-ready implementation path with practical setup steps, safer configuration defaults, and a clearer production checklist.

Use this page when you want the widget to become a real product surface: a dedicated swap page, a treasury action, an onboarding step, or a drawer-based utility flow inside a larger web app.

If you are still comparing layouts or config tradeoffs, review the LI.FI playground guide first, then come back here for the tighter integration sequence.

What the LiFi Widget is good for

The Gizmolab wrapper around @lifi/widget gives you a reusable React component for cross-chain swaps and bridging. It is useful when your product needs asset movement inside the app instead of sending users to a separate destination.

  • onboarding flows that require asset movement before users can continue
  • wallets and dashboards that need a built-in swap or bridge action
  • DeFi interfaces that want a cleaner cross-chain entry point
  • consumer apps that need a faster path to embedded transfer UX

Quick start

1. Install the package

npm install @lifi/widget

2. Mount the widget

Start with a minimal client-rendered page. Confirm the widget loads in the exact container where users will interact with it before you add chain restrictions, fee logic, or custom theming.

"use client";

import React from "react";
import LiFiWidget from "@/components/open-source-components/lifi-widget/LiFiWidget";

export default function LiFiWidgetDemo() {
  return (
    <div className="w-full min-h-screen flex justify-center items-center">
      <LiFiWidget integrator="YourAppName" />
    </div>
  );
}
Keep the first pass simple: prove the integration works, then shape the user experience. Teams that debug routing, wallet behavior, and product styling all at once usually slow themselves down.

Recommended integration flow

The safest order is install first, render the widget in a stable page or panel, and only then narrow the experience with chain, token, fee, or theme rules.

  1. prove the integration works in your real layout
  2. decide whether the widget is a destination or a step in a larger flow
  3. restrict chains or tokens only when product rules require it
  4. add fees and branded styling after the base user path is stable

That separation matters because integration bugs and UX decisions are two different jobs. Treat them separately and your rollout gets easier to test.

Core props worth using

integrator

Identify the application or company name tied to the widget integration.

variant / subvariant

Choose whether the widget should feel compact, wide, or drawer-based depending on the page surface.

appearance

Keep the widget aligned with the surrounding UI using the supported light or dark appearance modes.

allowedChains / allowedTokens

Narrow the experience when your product only supports a limited route or asset set.

fee / feeConfig

Add monetization only when disclosure and support expectations are clear.

theme

Apply brand styling so the widget feels native instead of bolted on.

transactionSettings

Control transaction behavior when you need tighter product-level defaults.

walletManagement

Tune wallet behavior when your integration needs a more opinionated connection experience.

Example: branded integration with tighter chain control

Use a wider layout when swap or bridge activity is the primary job of the screen. This works well for a dedicated trading or treasury surface.

"use client";

import LiFiWidget from "@/components/open-source-components/lifi-widget/LiFiWidget";

export default function SwapPanel() {
  return (
    <LiFiWidget
      integrator="YourAppName"
      variant="wide"
      appearance="dark"
      allowedChains={[1, 137, 8453]}
      fee={0.003}
      theme={{
        container: {
          borderRadius: "20px",
          border: "1px solid rgba(255,255,255,0.08)",
        },
        colors: {
          primary: "#7C3AED",
          background: "#0B0B12",
          surface: "#12131A",
          text: "#FFFFFF",
          textSecondary: "#A1A1AA",
        },
      }}
    />
  );
}

Example: centralize widget configuration

Reach for a shared WidgetConfig object when multiple routes should inherit the same widget behavior.

"use client";

import LiFiWidget from "@/components/open-source-components/lifi-widget/LiFiWidget";
import type { WidgetConfig } from "@lifi/widget";

const widgetConfig: WidgetConfig = {
  variant: "compact",
  subvariant: "default",
  appearance: "dark",
  languages: { default: "en" },
};

export default function EmbeddedSwapCard() {
  return <LiFiWidget integrator="YourAppName" config={widgetConfig} />;
}

Implementation decisions worth making early

Decide whether the widget is a destination or a step

A dedicated swap page needs a broader layout and more surrounding context. An embedded action inside onboarding or deposits usually needs fewer controls and a tighter scope.

Decide how much choice users should have

A broad cross-chain experience can be powerful, but it can also create unnecessary branching. If your product only supports a narrow route, configure the widget narrowly.

Decide whether fees belong in version one

The component supports monetization, but many teams are better served by validating route quality and support burden before adding fee logic.

Production checklist

  • Install @lifi/widget.
  • Mount the Gizmolab LiFiWidget component in a client-rendered surface.
  • Pass an integrator value.
  • Choose a layout with variant, subvariant, and appearance.
  • Restrict chains or tokens only when the product requires it.
  • Validate the widget in the real page container, especially inside tabs, drawers, or modals.
  • Review fee presentation before enabling fee or feeConfig.

Related docs and components

Explore the live LiFi Widget component referenceCompare another embedded trading-style component surfaceStart with the Next.js installation guideReview the broader Gizmolab UI docs introduction

FAQ

Do I need to build swap and bridge logic from scratch?

No. The point of the LiFi Widget is to give you a ready-made UI surface for cross-chain swaps and bridging, which you can then adapt with configuration and product-level UX decisions.

Can I brand the widget to match my app?

Yes. The Gizmolab wrapper exposes theming controls for container styling, colors, and typography alongside layout and appearance props.

Can I limit which chains or tokens users see?

Yes. Use allowedChains and allowedTokens when you need a narrower or policy-driven experience.

Should I use individual props or a WidgetConfig object?

Use individual props when you want clarity in a single-page implementation. Use a shared WidgetConfig object when you want centralized control or shared defaults across several routes.

Add the LiFi Widget with less integration overhead

Start with a minimal embed, confirm the widget works inside the real layout, and then layer in branding, chain restrictions, token restrictions, or fee logic only where the product actually needs them.