@gearbox-protocol/ui-kit

v4.3.0

Published

4 days ago

Internal UI components

0High
0Medium
0Low

Permissionless UI

UI components for internal use - framework-agnostic React component library built with Tailwind CSS 4.

Installation

pnpm install @gearbox-protocol/ui-kit

For Next.js projects, also install Next.js:

pnpm install next

Setup

1. Configure Tailwind CSS

Create or update your tailwind.config.ts:

import type { Config } from "tailwindcss";
import { preset } from "@gearbox-protocol/ui-kit/preset";

const config: Config = {
  presets: [preset],
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/@gearbox-protocol/ui-kit/dist/**/*.js",
  ],
};

export default config;

2. Import Global Styles

In your main entry file:

import "@gearbox-protocol/ui-kit/globals.css";

3. Add Theme Provider (Optional)

For dark mode support:

import { ThemeProvider, ThemeScript } from "@gearbox-protocol/ui-kit";

// For Next.js App Router
export default function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning>
      <head>
        {/* Prevents flash of white cards on page load */}
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider defaultTheme="system">
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

// For other frameworks (CRA, Vite, etc.)
function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* Your app */}
    </ThemeProvider>
  );
}

Usage

Base component system

The base/ layer (src/components/base/) is the canonical component system shared by all Gearbox frontends. Its contract lives in docs/component-registry.md. Key points:

SDK-typed props — components accept @gearbox-protocol/sdk/model entities (Token, TokenAmount, HistorySeries, PnlBreakdown, …), not a spread of scalars.
Design only — props in, JSX out; no data hooks, no fetching.
One name — one implementation — base components replaced the old StatBadge, PageTitle and DetailedPageTitle exports, and VSpace now takes size on the shared spacing scale (a number is the pixel escape hatch, mobileSize overrides the mobile half).

import {
  AmountInput,
  InfoLine,
  InfoList,
  ReviewButton,
  Stack,
  TokenAmount,
  VSpace,
} from '@gearbox-protocol/ui-kit';

function DepositDialog({ token, balance }) {
  const [amount, setAmount] = useState(0n);
  return (
    <Stack gap="md">
      <AmountInput amount={amount} onAmount={setAmount} token={token} balance={balance} />
      <VSpace size="md" />
      <InfoList>
        <InfoLine title={<span>You deposit</span>} value={<TokenAmount data={{ value: amount, valueUsd: null, token }} />} />
      </InfoList>
      <ReviewButton disabled={amount === 0n} error={null} onClick={openVerify} />
    </Stack>
  );
}

Test ids of base components are Node-safe via @gearbox-protocol/ui-kit/test-ids.

Framework-agnostic (works everywhere)

import { Button, Input, Card } from '@gearbox-protocol/ui-kit';

function MyComponent() {
  return (
    <Card>
      <Input placeholder="Enter text" />
      <Button variant="default">Submit</Button>
    </Card>
  );
}

Next.js optimized

import { TokenIcon, BackButton, SIWEClientProvider } from '@gearbox-protocol/ui-kit/next';

// Uses Next.js Image, Link and useRouter
<TokenIcon symbol="ETH" size={48} />
<BackButton href="/dashboard" text="Back" />

Wallet UI and SIWE (optional ConnectKit)

ConnectRequired, SignInRequired, and editable tables that gate actions use a small wallet UI adapter via WalletUIProvider. You can wire ConnectKit without importing it in your app code, or provide your own adapter (e.g. RainbowKit).

ConnectKit (recommended when you already use ConnectKit + SIWE)

Install: pnpm add connectkit (optional peer dependency).

import { ConnectKitProvider } from "connectkit";
import {
  ConnectKitWalletAdapter,
  SIWEClientProvider,
} from "@gearbox-protocol/ui-kit/connectkit";

<WagmiProvider config={config}>
  <QueryClientProvider client={queryClient}>
    <SIWEClientProvider apiRoutePrefix="/api/auth" onRefresh={() => {}}>
      <ConnectKitProvider>
        <ConnectKitWalletAdapter>
          {children}
        </ConnectKitWalletAdapter>
      </ConnectKitProvider>
    </SIWEClientProvider>
  </QueryClientProvider>
</WagmiProvider>

Next.js App Router — use the Next-specific SIWE wrapper (calls router.refresh() after sign-in/out):

import { SIWEClientProvider } from "@gearbox-protocol/ui-kit/next/connectkit";
import { ConnectKitWalletAdapter } from "@gearbox-protocol/ui-kit/connectkit";

<SIWEClientProvider apiRoutePrefix="/api/auth">
  <ConnectKitProvider>
    <ConnectKitWalletAdapter>{children}</ConnectKitWalletAdapter>
  </ConnectKitProvider>
</SIWEClientProvider>

RainbowKit or custom wallet modal

You do not need connectkit if you only use WalletUIProvider with your own openConnectModal (and optional SIWE fields). Example with RainbowKit:

import { useConnectModal } from "@rainbow-me/rainbowkit";
import { WalletUIProvider } from "@gearbox-protocol/ui-kit";

function RainbowKitWalletAdapter({ children }: { children: React.ReactNode }) {
  const { openConnectModal } = useConnectModal();
  return (
    <WalletUIProvider
      value={{
        openConnectModal: openConnectModal ?? (() => {}),
      }}
    >
      {children}
    </WalletUIProvider>
  );
}

Without any WalletUIProvider, ConnectRequired / SignInRequired skip their connect/sign-in UI and render children (graceful degradation).

Custom components

import { TokenIcon, BackButton } from '@gearbox-protocol/ui-kit';
import MyImage from './MyImage';
import { Link } from 'react-router-dom';

<TokenIcon symbol="ETH" ImageComponent={MyImage} />
<BackButton href="/back" LinkComponent={Link} />

Dependencies

Required Peer Dependencies

These dependencies must be installed in your project:

pnpm install react react-dom @gearbox-protocol/sdk @tanstack/react-query viem wagmi reactochart

| Package | Version | Description | |---------|---------|-------------| | react | ^18 || ^19 | React library | | react-dom | ^18 || ^19 | React DOM | | @gearbox-protocol/sdk | * | Gearbox Protocol SDK | | @tanstack/react-query | ^5.64.1 | Data fetching and caching | | viem | ^2.0.0 | Ethereum library | | wagmi | ^2.0.0 | React hooks for Ethereum | | reactochart | ^6.1.1 | Charts library (used in Graph components) |

Optional Peer Dependencies

Install only if you use specific features:

| Package | Version | When to Install | |---------|---------|-----------------| | connectkit | ^1.8.0 | ConnectKit UI, @gearbox-protocol/ui-kit/connectkit, or SIWE via ConnectKit | | next | >=13 | Using @gearbox-protocol/ui-kit/next exports | | react-intl | ^6.0.0 || ^7.0.0 | Using internationalization features | | react-router-dom | ^6.0.0 || ^7.0.0 | Using router-based navigation (non-Next.js) | | sonner | ^2.0.0 | Using toast notifications |

Installation Examples

Minimal setup (basic components only):

pnpm install @gearbox-protocol/ui-kit react react-dom

Full Web3 setup (wagmi; no ConnectKit):

pnpm install @gearbox-protocol/ui-kit \
  react react-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi reactochart

Full Web3 + ConnectKit adapters:

pnpm install @gearbox-protocol/ui-kit \
  react react-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart

With Next.js:

pnpm install @gearbox-protocol/ui-kit \
  react react-dom next \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi reactochart

With Next.js and ConnectKit entrypoints:

pnpm install @gearbox-protocol/ui-kit \
  react react-dom next \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart

With routing (React Router):

pnpm install @gearbox-protocol/ui-kit \
  react react-dom react-router-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi reactochart

With internationalization:

pnpm install @gearbox-protocol/ui-kit react-intl

Package Exports

The library provides several entry points:

| Export | Description | |--------|-------------| | @gearbox-protocol/ui-kit | Main entry - all framework-agnostic components | | @gearbox-protocol/ui-kit/next | Next.js optimized components (Image, Link, Router) | | @gearbox-protocol/ui-kit/connectkit | ConnectKit bridge: ConnectKitWalletAdapter, SIWEClientProvider | | @gearbox-protocol/ui-kit/next/connectkit | Next.js SIWEClientProvider with router.refresh() | | @gearbox-protocol/ui-kit/preset | Tailwind CSS preset | | @gearbox-protocol/ui-kit/tailwind | Tailwind CSS config | | @gearbox-protocol/ui-kit/globals.css | Global CSS styles | | @gearbox-protocol/ui-kit/grid-safelist.css | Grid safelist CSS | | @gearbox-protocol/ui-kit/tx-preview | Transaction preview + confirm modal (isolated WIP module) |

Troubleshooting

Module not found errors

If you see errors like Cannot find module '@gearbox-protocol/sdk', install the missing peer dependency:

pnpm install @gearbox-protocol/sdk

TypeScript errors

Install type definitions for React:

pnpm install -D @types/react @types/react-dom

Tailwind styles not working

Make sure you've added the library's dist folder to your Tailwind content config:

content: [
  "./node_modules/@gearbox-protocol/ui-kit/dist/**/*.js",
]

Import the global styles in your entry file:

import "@gearbox-protocol/ui-kit/globals.css";

Next.js specific components not working

Make sure you've installed Next.js and are importing from the correct path:

// ✅ Correct
import { TokenIcon } from '@gearbox-protocol/ui-kit/next';

// ❌ Wrong - these won't have Next.js optimizations
import { TokenIcon } from '@gearbox-protocol/ui-kit';

Important information for contributors

As a contributor to the Gearbox Protocol GitHub repository, your pull requests indicate acceptance of our Gearbox Contribution Agreement. This agreement outlines that you assign the Intellectual Property Rights of your contributions to the Gearbox Foundation. This helps safeguard the Gearbox protocol and ensure the accumulation of its intellectual property. Contributions become part of the repository and may be used for various purposes, including commercial. As recognition for your expertise and work, you receive the opportunity to participate in the protocol's development and the potential to see your work integrated within it. The full Gearbox Contribution Agreement is accessible within the repository for comprehensive understanding. [Let's innovate together!]