ConnectModal Component

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/ConnectModal/ConnectModal.svelte
• src/lib/ConnectModal/index.d.ts
• src/lib/ConnectModal/ConnectModal.svelte.d.ts
• src/lib/SuiModule/SuiModule.svelte
• README.md
• src/routes/+page.svelte
• package.json

The ConnectModal is a pre-built, responsive Svelte component that provides a user interface for selecting and connecting to a Sui wallet. It is a core part of the sui-svelte-wallet-kit, designed to be used internally by the main SuiModule component. The modal displays a list of detected installed wallets, other available wallets, and an option for Google zkLogin via Enoki if configured.

While it is primarily managed by the SuiModule and triggered by the ConnectButton, it can also be accessed programmatically for more advanced use cases like implementing a "switch wallet" feature. The component handles the logic for displaying wallets, differentiating between installed and not-installed ones, and returning the user's selection.

Sources: README.md, src/lib/SuiModule/SuiModule.svelte:1120-1131, src/lib/ConnectModal/ConnectModal.svelte

Architecture and Integration

The ConnectModal is designed to be a child component of SuiModule. The SuiModule is responsible for wallet discovery and passes the list of available wallets and zkLogin configuration down to the ConnectModal via props.

Sources: src/lib/SuiModule/SuiModule.svelte:1120-1131

The following diagram illustrates the component hierarchy:

The component is exported from the library's main entry point and can be imported directly, although the primary intended use is internal to SuiModule.

Sources: package.json:44-47, src/lib/index.js:3

Core Functionality

Wallet Display Logic

The modal receives a list of all available wallets and dynamically organizes them for the user.

1. Categorization: Wallets are divided into detectedWallets (installed) and otherWallets (not installed).
2. zkLogin: The "Sign in with Google" option is displayed if a valid zkLoginGoogle configuration is provided to the SuiModule.
3. Display Order: Installed wallets are shown first. Other wallets are initially hidden behind a "More" toggle button to keep the UI clean.
4. Install Hint: If a user clicks on a wallet that is not installed, an informational hint appears with a direct link to install it from the relevant web store. The modal remains open, allowing the user to select another wallet.

Sources: src/lib/ConnectModal/ConnectModal.svelte:70-78, src/lib/ConnectModal/ConnectModal.svelte:200-219, src/lib/ConnectModal/ConnectModal.svelte:145-156

This flow is visualized in the diagram below:

User Interaction and State

The ConnectModal is built using a native HTML <dialog> element, which ensures it is rendered in the top layer of the page. Its visibility is controlled by an internal isOpen state.

The primary method for interacting with the modal is openAndWaitForResponse(). This function:

1. Opens the modal dialog.
2. Returns a Promise that waits for user interaction.
3. The promise resolves with a ConnectModalResponse object containing the selected wallet's details if a choice is made.
4. The promise resolves with undefined if the user closes the modal without making a selection (e.g., by pressing Escape or clicking the overlay).

Sources: src/lib/ConnectModal/ConnectModal.svelte:94-105, src/lib/ConnectModal/ConnectModal.svelte:111-117

The sequence diagram below shows the interaction flow when opening the modal and selecting a wallet.

API Reference

The component's API is defined through its props, instance methods, and the response structure of its primary method.

Sources: src/lib/ConnectModal/ConnectModal.svelte.d.ts, src/lib/ConnectModal/index.d.ts

Props (ConnectModalProps)

These props are passed to the ConnectModal component, typically from SuiModule.

Prop	Type	Description
availableWallets	SuiWallet[]	An array of available wallets to display in the modal.
onPickInstalled	(wallet: SuiWallet) => void	Optional callback fired immediately when a user picks an installed wallet to preserve the user gesture.
zkLoginGoogle	ZkLoginGoogleConfig | null	Optional configuration for enabling Enoki zkLogin with Google.

Sources: src/lib/ConnectModal/ConnectModal.svelte.d.ts:11-25, src/lib/SuiModule/SuiModule.svelte:1122-1124

Instance Methods (ConnectModalInstance)

These methods can be called on a reference to the ConnectModal instance.

Method	Return Type	Description
openAndWaitForResponse()	Promise<ConnectModalResponse | undefined>	Opens the modal and returns a promise that resolves with the user's selection or undefined if cancelled.

Sources: src/lib/ConnectModal/ConnectModal.svelte.d.ts:31-35

Response Object (ConnectModalResponse)

This is the structure of the object returned when the openAndWaitForResponse() promise resolves successfully.

Field	Type	Description
wallet	SuiWallet	The wallet object selected by the user.
installed	boolean	true if the selected wallet is installed, otherwise false.
started	boolean	Optional. true if the connection process was started by the modal itself.

Sources: src/lib/ConnectModal/ConnectModal.svelte.d.ts:5-10

UI and Styling

The modal's structure is defined in ConnectModal.svelte and can be customized using global CSS overrides.

Key CSS classes for styling:

• .modal-overlay: The semi-transparent background.
• .modal-content: The main container for the modal.
• .wallet-button: The button for each wallet in the list.
• .install-hint: The alert box shown for non-installed wallets.
• .close-button: The 'X' button in the header.

Sources: README.md, src/lib/ConnectModal/ConnectModal.svelte:311-468

An example of overriding styles is provided in the project's documentation:

:global(.modal-overlay) {
	background: rgba(0, 0, 0, 0.8);
}
:global(.modal-content) {
	background: #1a1a1a;
	border: 1px solid #333;
}
:global(.wallet-button:hover) {
	border-color: #667eea;
	background: #333;
}

Sources: README.md

Programmatic Usage

The ConnectModal can be controlled programmatically via the getConnectModal function exported from SuiModule. This allows for custom flows, such as a "Switch Wallet" button that opens the modal even when a wallet is already connected. The switchWallet helper function is a convenient wrapper for this functionality.

<script>
	import { switchWallet } from 'sui-svelte-wallet-kit';

	// Programmatically opens the modal to switch wallets
	const simpleSwitch = async () => {
		const res = await switchWallet();
		if (res?.connected) {
			console.log('Switched to', res.wallet?.name);
		}
	};
</script>

Sources: README.md, src/routes/+page.svelte:220-236

Conclusion

The ConnectModal component is a crucial element of the sui-svelte-wallet-kit, providing a polished and user-friendly interface for wallet selection. Its tight integration with SuiModule, clear separation of concerns, and programmatic accessibility make it both easy to use out-of-the-box and flexible enough for custom implementations. By handling wallet discovery display, installation states, and user selection, it abstracts away significant complexity from the dApp developer.