@gearbox-protocol/ui-kit

中文文档
4.12.1发布于 2026/11/16MITTypeScriptESM + CJS近 30 天下载 4479

Internal UI components

原始使用文档
文档目录23 节
  1. Installation
  2. Setup
  3. 1. Configure Tailwind CSS
  4. 2. Import Global Styles
  5. 3. Add Theme Provider (Optional)
  6. Usage
  7. Base component system
  8. Framework-agnostic (works everywhere)
  9. Next.js optimized
  10. Wallet UI and SIWE (optional ConnectKit)
  11. User agreements
  12. Custom components
  13. Dependencies
  14. Required Peer Dependencies
  15. Optional Peer Dependencies
  16. Installation Examples
  17. Package Exports
  18. Troubleshooting
  19. Module not found errors
  20. TypeScript errors
  21. Tailwind styles not working
  22. Next.js specific components not working
  23. Important information for contributors

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).

User agreements

@gearbox-protocol/ui-kit/user-agreements lets wallet-connected Gearbox apps check whether an account has signed the current legal agreement, ask the user to sign it, and detect blocked regions. It contains the legal message texts, AgreementService for talking to the agreements server, and the useAgreement and useBlockedRegion hooks, which need wagmi and @tanstack/react-query. It is a separate entry point that the main entry never imports, so apps that don't use agreements neither load it nor need those packages. See User agreements for the full documentation, and Migrating from auth-kit if you used @gearbox-protocol/auth-kit.

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

Optional Peer Dependencies

Install only if you use specific features:

PackageVersionWhen to Install
connectkit^1.8.0ConnectKit UI, @gearbox-protocol/ui-kit/connectkit, or SIWE via ConnectKit
next>=13Using @gearbox-protocol/ui-kit/next exports
react-intl^6.0.0 || ^7.0.0Using internationalization features
react-router-dom^6.0.0 || ^7.0.0Using router-based navigation (non-Next.js)
sonner^2.0.0Using 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:

ExportDescription
@gearbox-protocol/ui-kitMain entry - all framework-agnostic components
@gearbox-protocol/ui-kit/nextNext.js optimized components (Image, Link, Router)
@gearbox-protocol/ui-kit/connectkitConnectKit bridge: ConnectKitWalletAdapter, SIWEClientProvider
@gearbox-protocol/ui-kit/next/connectkitNext.js SIWEClientProvider with router.refresh()
@gearbox-protocol/ui-kit/user-agreementsLegal agreement signing and checks, see User agreements
@gearbox-protocol/ui-kit/presetTailwind CSS preset
@gearbox-protocol/ui-kit/tailwindTailwind CSS config
@gearbox-protocol/ui-kit/globals.cssGlobal CSS styles
@gearbox-protocol/ui-kit/grid-safelist.cssGrid safelist CSS
@gearbox-protocol/ui-kit/tx-previewTransaction 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

  1. Make sure you've added the library's dist folder to your Tailwind content config:
content: [
  "./node_modules/@gearbox-protocol/ui-kit/dist/**/*.js",
]
  1. 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!]

版本与发布记录

@gearbox-protocol/ui-kit 共发布 244 个版本,首次发布于 2026/04/03;过去 12 个月发布了 244 个版本。

版本发布日期距今
4.12.1latest2026/11/16今天
4.11.0-next.6next2026/11/0412 天前
4.12.02026/11/0313 天前
4.11.02026/10/3017 天前
4.11.0-next.52026/10/3017 天前
4.11.0-next.42026/10/2819 天前

关于 @gearbox-protocol/ui-kit 的常见问题

@gearbox-protocol/ui-kit 是什么?

Internal UI components

如何安装 @gearbox-protocol/ui-kit?

在项目目录运行 npm install @gearbox-protocol/ui-kit,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:viem(^2.0.0)、react(^18 || ^19)、sonner(^2.0.0)、@types/react(^18 || ^19)、@gearbox-protocol/sdk(*)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gearbox-protocol/ui-kit 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gearbox-protocol/ui-kit 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gearbox-protocol/ui-kit 可以商用吗?

@gearbox-protocol/ui-kit 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gearbox-protocol/ui-kit 的下载量有多少?

根据 npm 官方下载统计,@gearbox-protocol/ui-kit 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,479 次,日均约 149 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gearbox-protocol/ui-kit 还在维护吗?

最新版本 4.12.1 发布于 2026/11/16(今天);至今共发布 244 个版本,其中过去 12 个月发布了 244 个;首次发布于 2026/04/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。