0
# Widget Management
1

2
Core functionality for initializing and managing the Torus wallet widget, including configuration, display control, and lifecycle management.
3

4
## Capabilities
5

6
### Constructor
7

8
Creates a new Torus instance with optional configuration parameters.
9

10
```typescript { .api }
11
/**
12
 * Creates a new Torus instance with configurable widget settings
13
 * @param args - Optional configuration parameters
14
 */
15
constructor(args?: TorusCtorArgs);
16

17
interface TorusCtorArgs {
18
  /** Widget button position on the page */
19
  buttonPosition?: BUTTON_POSITION_TYPE;
20
  /** Size of the widget button in pixels */
21
  buttonSize?: number;
22
  /** Z-index for modal and iframe elements */
23
  modalZIndex?: number;
24
  /** API key for Torus services */
25
  apiKey?: string;
26
}
27

28
type BUTTON_POSITION_TYPE = "bottom-left" | "top-left" | "bottom-right" | "top-right";
29
```
30

31
**Usage Example:**
32

33
```typescript
34
import Torus from "@toruslabs/torus-embed";
35

36
const torus = new Torus({
37
  buttonPosition: "bottom-right",
38
  buttonSize: 64,
39
  modalZIndex: 100000,
40
  apiKey: "your-api-key"
41
});
42
```
43

44
### Widget Initialization
45

46
Initializes the Torus widget with network and configuration settings.
47

48
```typescript { .api }
49
/**
50
 * Initialize the Torus widget - must be called before any other operations
51
 * @param params - Initialization parameters including network and UI settings
52
 * @returns Promise that resolves when initialization is complete
53
 */
54
init(params?: TorusParams): Promise<void>;
55

56
interface TorusParams {
57
  /** Torus network configuration */
58
  network?: NetworkInterface;
59
  /** Build environment for Torus widget */
60
  buildEnv?: TORUS_BUILD_ENV_TYPE;
61
  /** Enable debug logging */
62
  enableLogging?: boolean;
63
  /** Show/hide the Torus widget button */
64
  showTorusButton?: boolean;
65
  /** Custom login provider configurations */
66
  loginConfig?: LoginConfig;
67
  /** Version integrity settings */
68
  integrity?: IntegrityParams;
69
  /** White label customization */
70
  whiteLabel?: WhiteLabelParams;
71
  /** Enable WalletConnect support */
72
  useWalletConnect?: boolean;
73
  /** Multi-factor authentication level */
74
  mfaLevel?: "none" | "default" | "optional" | "mandatory";
75
}
76

77
interface NetworkInterface {
78
  /** Ethereum network host */
79
  host: ETHEREUM_NETWORK_TYPE | string;
80
  /** Network chain ID */
81
  chainId?: number;
82
  /** Display name for the network */
83
  networkName?: string;
84
  /** Block explorer URL */
85
  blockExplorer?: string;
86
  /** Native currency ticker */
87
  ticker?: string;
88
  /** Native currency display name */
89
  tickerName?: string;
90
}
91
```
92

93
**Usage Example:**
94

95
```typescript
96
await torus.init({
97
  buildEnv: "production",
98
  network: {
99
    host: "mainnet",
100
    chainId: 1,
101
    networkName: "Ethereum Mainnet",
102
    blockExplorer: "https://etherscan.io",
103
    ticker: "ETH",
104
    tickerName: "Ether"
105
  },
106
  showTorusButton: true,
107
  enableLogging: false,
108
  mfaLevel: "default"
109
});
110
```
111

112
### Widget Display Control
113

114
Control the visibility of the Torus widget button.
115

116
```typescript { .api }
117
/**
118
 * Hide the Torus widget button from the page
119
 */
120
hideTorusButton(): void;
121

122
/**
123
 * Show the Torus widget button on the page
124
 */
125
showTorusButton(): void;
126
```
127

128
**Usage Example:**
129

130
```typescript
131
// Hide button during onboarding
132
torus.hideTorusButton();
133

134
// Show button after user setup
135
torus.showTorusButton();
136
```
137

138
### Widget Cleanup
139

140
Methods for cleaning up widget state and DOM elements.
141

142
```typescript { .api }
143
/**
144
 * Clear initialization state and remove DOM elements
145
 * Does not log out the user
146
 */
147
clearInit(): void;
148

149
/**
150
 * Complete cleanup including logout and DOM element removal
151
 * @returns Promise that resolves when cleanup is complete
152
 */
153
cleanUp(): Promise<void>;
154
```
155

156
**Usage Example:**
157

158
```typescript
159
// Clean up when changing configuration
160
torus.clearInit();
161
await torus.init(newConfig);
162

163
// Complete cleanup when done with Torus
164
await torus.cleanUp();
165
```
166

167
### Widget State Properties
168

169
Access current widget state and configuration.
170

171
```typescript { .api }
172
/** Current button position */
173
readonly buttonPosition: BUTTON_POSITION_TYPE;
174

175
/** Current button size in pixels */
176
readonly buttonSize: number;
177

178
/** Current Torus service URL */
179
readonly torusUrl: string;
180

181
/** Whether widget is initialized */
182
readonly isInitialized: boolean;
183

184
/** Whether Torus button is visible */
185
readonly torusWidgetVisibility: boolean;
186

187
/** Current API key */
188
readonly apiKey: string;
189

190
/** Current modal z-index */
191
readonly modalZIndex: number;
192

193
/** Current alert z-index */
194
readonly alertZIndex: number;
195

196
/** Current white label configuration */
197
readonly whiteLabel: WhiteLabelParams;
198

199
/** Current verifier being used */
200
readonly currentVerifier: string;
201

202
/** Requested verifier for login */
203
readonly requestedVerifier: string;
204

205
/** Current embed translation settings */
206
readonly embedTranslations: EMBED_TRANSLATION_ITEM;
207
```
208

209
### Configuration Types
210

211
```typescript { .api }
212
type TORUS_BUILD_ENV_TYPE = 
213
  | "production"    // Production environment (https://app.tor.us)
214
  | "development"   // Development environment (localhost:4050)
215
  | "binance"       // Binance environment (https://binance.tor.us)
216
  | "testing"       // Testing environment (https://testing.tor.us)
217
  | "lrc"           // LRC environment (https://lrc.tor.us)
218
  | "beta"          // Beta environment (https://beta.tor.us)
219
  | "bnb"           // BNB environment (https://bnb.tor.us)
220
  | "polygon"       // Polygon environment (https://polygon.tor.us)
221
  | "alpha";        // Alpha environment
222

223
type ETHEREUM_NETWORK_TYPE = 
224
  | "sepolia" | "mainnet" | "goerli" | "localhost"
225
  | "matic" | "mumbai" | "xdai" | "bsc_mainnet" | "bsc_testnet";
226

227
interface IntegrityParams {
228
  /** Specific version of torus-website to load */
229
  version?: string;
230
}
231

232
interface WhiteLabelParams {
233
  /** Theme customization */
234
  theme: ThemeParams;
235
  /** Default language for the interface */
236
  defaultLanguage?: string;
237
  /** Logo URL for light mode */
238
  logoDark: string;
239
  /** Logo URL for dark mode */
240
  logoLight: string;
241
  /** Hide topup functionality */
242
  topupHide?: boolean;
243
  /** Hide featured billboard */
244
  featuredBillboardHide?: boolean;
245
  /** Hide disclaimers on login */
246
  disclaimerHide?: boolean;
247
  /** Terms and conditions links */
248
  tncLink?: LocaleLinks<string>;
249
  /** Privacy policy links */
250
  privacyPolicy?: LocaleLinks<string>;
251
  /** Contact links */
252
  contactLink?: LocaleLinks<string>;
253
  /** Custom translations */
254
  customTranslations?: LocaleLinks<unknown>;
255
}
256

257
interface ThemeParams {
258
  /** Enable dark mode */
259
  isDark: boolean;
260
  /** Custom color configuration */
261
  colors: Record<string, string>;
262
}
263

264
interface LocaleLinks<T> {
265
  en?: T;
266
  ja?: T;
267
  ko?: T;
268
  de?: T;
269
  zh?: T;
270
  es?: T;
271
}
272

273
interface EMBED_TRANSLATION_ITEM {
274
  continue: string;
275
  actionRequired: string;
276
  pendingAction: string;
277
  cookiesRequired: string;
278
  enableCookies: string;
279
  clickHere: string;
280
}
281
```