0
# RainbowKit
1

2
RainbowKit is a comprehensive React library that simplifies wallet connection functionality for decentralized applications (dApps). Built on top of wagmi and viem, it provides out-of-the-box wallet management with extensive customization options, supporting 66 wallet connectors and connection methods.
3

4
## Package Information
5

6
- **Package Name**: @rainbow-me/rainbowkit
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @rainbow-me/rainbowkit`
10

11
## Core Imports
12

13
```typescript
14
import { RainbowKitProvider, ConnectButton, getDefaultConfig } from '@rainbow-me/rainbowkit';
15
import { metaMaskWallet, coinbaseWallet } from '@rainbow-me/rainbowkit/wallets';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { RainbowKitProvider, ConnectButton, getDefaultConfig } = require('@rainbow-me/rainbowkit');
22
```
23

24
## Basic Usage
25

26
```typescript
27
import '@rainbow-me/rainbowkit/styles.css';
28
import { getDefaultConfig, RainbowKitProvider, ConnectButton } from '@rainbow-me/rainbowkit';
29
import { WagmiProvider } from 'wagmi';
30
import { mainnet, polygon, optimism, arbitrum, base } from 'wagmi/chains';
31
import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
32

33
const config = getDefaultConfig({
34
  appName: 'My RainbowKit App',
35
  projectId: 'YOUR_PROJECT_ID',
36
  chains: [mainnet, polygon, optimism, arbitrum, base],
37
});
38

39
const queryClient = new QueryClient();
40

41
function App() {
42
  return (
43
    <WagmiProvider config={config}>
44
      <QueryClientProvider client={queryClient}>
45
        <RainbowKitProvider>
46
          <ConnectButton />
47
        </RainbowKitProvider>
48
      </QueryClientProvider>
49
    </WagmiProvider>
50
  );
51
}
52
```
53

54
## Architecture
55

56
RainbowKit is built around several key components:
57

58
- **Provider System**: `RainbowKitProvider` wraps your app and manages global state, theming, and localization
59
- **Connection Components**: `ConnectButton` and `WalletButton` provide pre-built UI for wallet connections
60
- **Configuration API**: `getDefaultConfig` and wallet connector functions simplify setup
61
- **Modal System**: Built-in modals for account management, chain switching, and wallet selection with customizable triggers
62
- **Wallet Ecosystem**: 66 supported wallets with standardized connector interface
63
- **Theme Engine**: Flexible theming system with built-in themes and custom theme creation
64
- **Type Safety**: Full TypeScript integration with comprehensive type definitions
65

66
## Capabilities
67

68
### Core Components
69

70
Primary React components for wallet connection UI and state management.
71

72
```typescript { .api }
73
function ConnectButton(props?: ConnectButtonProps): JSX.Element;
74

75
function WalletButton(props?: WalletButtonProps): JSX.Element;
76

77
function RainbowKitProvider(props: RainbowKitProviderProps): JSX.Element;
78

79
interface ConnectButtonProps {
80
  accountStatus?: ResponsiveValue<AccountStatus>;
81
  showBalance?: ResponsiveValue<boolean>;
82
  chainStatus?: ResponsiveValue<ChainStatus>;
83
  label?: string;
84
}
85

86
interface WalletButtonProps {
87
  wallet?: string;
88
}
89

90
interface RainbowKitProviderProps {
91
  children: ReactNode;
92
  initialChain?: Chain | number;
93
  id?: string;
94
  theme?: Theme | null;
95
  showRecentTransactions?: boolean;
96
  appInfo?: {
97
    appName?: string;
98
    learnMoreUrl?: string;
99
    disclaimer?: DisclaimerComponent;
100
  };
101
  coolMode?: boolean;
102
  avatar?: AvatarComponent;
103
  modalSize?: ModalSizes;
104
  locale?: Locale;
105
}
106
```
107

108
[Core Components](./core-components.md)
109

110
### Configuration
111

112
Setup and configuration functions for integrating RainbowKit with wagmi and custom wallet selections.
113

114
```typescript { .api }
115
function getDefaultConfig<T extends readonly [Chain, ...Chain[]]>(
116
  parameters: GetDefaultConfigParameters<T>
117
): Config;
118

119
function connectorsForWallets(
120
  walletList: WalletList,
121
  parameters: ConnectorsForWalletsParameters
122
): CreateConnectorFn[];
123

124
function getWalletConnectConnector(
125
  parameters: WalletConnectConnectorParameters
126
): CreateConnectorFn;
127

128
interface GetDefaultConfigParameters<T extends readonly [Chain, ...Chain[]]> {
129
  appName: string;
130
  projectId: string;
131
  chains: T;
132
  appDescription?: string;
133
  appUrl?: string;
134
  appIcon?: string;
135
  wallets?: WalletList;
136
  ssr?: boolean;
137
}
138
```
139

140
[Configuration](./configuration.md)
141

142
### Wallet Connectors
143

144
Comprehensive collection of 66 wallet connectors for different wallet providers, exchanges, and hardware wallets.
145

146
```typescript { .api }
147
function metaMaskWallet(options?: WalletOptions): Wallet;
148
function coinbaseWallet(options?: WalletOptions): Wallet;
149
function rainbowWallet(options?: WalletOptions): Wallet;
150
function walletConnectWallet(options?: WalletOptions): Wallet;
151
// ... 62 additional wallet connectors
152

153
interface Wallet {
154
  id: string;
155
  name: string;
156
  iconUrl: string | (() => Promise<string>);
157
  iconBackground: string;
158
  createConnector: (walletDetails: WalletDetailsParams) => CreateConnectorFn;
159
}
160
```
161

162
[Wallet Connectors](./wallet-connectors.md)
163

164
### Modal Controls
165

166
React hooks for programmatically controlling wallet connection, account, and chain selection modals.
167

168
```typescript { .api }
169
function useConnectModal(): {
170
  connectModalOpen: boolean;
171
  openConnectModal?: () => void;
172
};
173

174
function useAccountModal(): {
175
  accountModalOpen: boolean;
176
  openAccountModal?: () => void;
177
};
178

179
function useChainModal(): {
180
  chainModalOpen: boolean;
181
  openChainModal?: () => void;
182
};
183
```
184

185
[Modal Controls](./modal-controls.md)
186

187
### Theming
188

189
Built-in themes and customization system for styling RainbowKit components.
190

191
```typescript { .api }
192
function lightTheme(options?: ThemeOptions): ThemeVars;
193
function darkTheme(options?: ThemeOptions): ThemeVars;
194
function midnightTheme(options?: ThemeOptions): ThemeVars;
195

196
function cssStringFromTheme(
197
  theme: ThemeVars | (() => ThemeVars),
198
  options?: { extends?: ThemeVars | (() => ThemeVars) }
199
): string;
200

201
interface ThemeOptions {
202
  accentColor?: string;
203
  accentColorForeground?: string;
204
  borderRadius?: 'large' | 'medium' | 'small' | 'none';
205
  fontStack?: 'system' | 'rounded';
206
  overlayBlur?: 'large' | 'small' | 'none';
207
}
208
```
209

210
[Theming](./theming.md)
211

212
### Authentication
213

214
SIWE (Sign-In with Ethereum) authentication integration for secure user authentication.
215

216
```typescript { .api }
217
function RainbowKitAuthenticationProvider<T>(
218
  props: RainbowKitAuthenticationProviderProps<T>
219
): JSX.Element;
220

221
function createAuthenticationAdapter<T>(
222
  adapter: AuthenticationAdapter<T>
223
): AuthenticationAdapter<T>;
224

225
interface AuthenticationAdapter<T> {
226
  getNonce: () => Promise<string>;
227
  createMessage: (args: CreateMessageArgs) => T;
228
  verify: (args: VerifyArgs<T>) => Promise<boolean>;
229
  signOut: () => Promise<void>;
230
}
231
```
232

233
[Authentication](./authentication.md)
234

235
## Types
236

237
### Core Types
238

239
```typescript { .api }
240
type ResponsiveValue<T> = T | { largeScreen: T; smallScreen: T };
241
type AccountStatus = 'full' | 'avatar' | 'address';
242
type ChainStatus = 'full' | 'icon' | 'name' | 'none';
243
type ModalSizes = 'compact' | 'wide';
244

245
type Locale =
246
  | 'ar' | 'ar-AR' | 'de' | 'de-DE' | 'en' | 'en-US' | 'es' | 'es-419'
247
  | 'fr' | 'fr-FR' | 'hi' | 'hi-IN' | 'id' | 'id-ID' | 'ja' | 'ja-JP'
248
  | 'ko' | 'ko-KR' | 'ms' | 'ms-MY' | 'pt' | 'pt-BR' | 'ru' | 'ru-RU'
249
  | 'th' | 'th-TH' | 'tr' | 'tr-TR' | 'ua' | 'uk-UA' | 'vi' | 'vi-VN'
250
  | 'zh' | 'zh-CN' | 'zh-HK' | 'zh-TW' | 'zh-Hans' | 'zh-Hant';
251

252
type WalletList = {
253
  groupName: string;
254
  wallets: CreateWalletFn[];
255
}[];
256

257
type AuthenticationStatus = 'loading' | 'unauthenticated' | 'authenticated';
258

259
interface RainbowKitChain extends Chain {
260
  iconUrl?: string | (() => Promise<string>);
261
  iconBackground?: string;
262
}
263
```