Customizing the Wallet List

Relevant source files

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

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

The sui-svelte-wallet-kit provides a flexible way to customize the appearance of the wallet list within the ConnectModal. Developers can change the display names of wallets and define a specific order, allowing for a more tailored user experience that can prioritize certain wallets.

This customization is achieved by passing a walletConfig object to the main SuiModule component. This configuration is then used internally to process the list of detected wallets before it is rendered in the connection modal.

Sources: README.md:35-37, src/lib/SuiModule/SuiModule.svelte:1218-1224

Configuration via walletConfig

The primary mechanism for customization is the walletConfig prop on the SuiModule component. This prop accepts an object conforming to the WalletConfig type, which contains two optional properties: customNames and ordering.

Sources: src/lib/SuiModule/types.ts:90-93, README.md:63-65

WalletConfig Data Structure

The WalletConfig interface defines the shape of the configuration object.

// src/lib/SuiModule/types.ts:90-93
export interface WalletConfig {
	customNames?: Record<string, string>;
	ordering?: string[];
}

Property	Type	Description
customNames	Record<string, string>	An object mapping a wallet's original detected name to a new custom display name. This only affects the display; internal identification remains unchanged.
ordering	string[]	An array of original wallet names defining the preferred order. Wallets listed here will appear first, followed by any unlisted wallets sorted alphabetically.

Sources: src/lib/SuiModule/types.ts:90-93, README.md:63-71

Usage Example

To apply customization, you pass the walletConfig object to SuiModule. The original wallet names must be used as keys for customNames and as values in the ordering array.

<script>
	import { SuiModule } from 'sui-svelte-wallet-kit';
	import type { WalletConfig } from 'sui-svelte-wallet-kit';

	const walletConfig: WalletConfig = {
		// Custom display names for wallets
		customNames: {
			'Slush — A Sui wallet': 'Slush',
			'Martian Sui Wallet': 'Martian',
		},
		// Custom ordering
		ordering: [
			'Slush — A Sui wallet', // Show Slush first
			'Suiet',                // Then Suiet
			'Martian Sui Wallet'    // Then Martian
		]
	};
</script>

<SuiModule {walletConfig}>
	<!-- Your dApp content -->
</SuiModule>

Sources: README.md:38-61, src/routes/+page.svelte:238-246

Wallet Processing Logic

When the SuiModule component initializes, it discovers available wallets and then applies the provided walletConfig. This logic is encapsulated within the applyWalletConfig function.

Sources: src/lib/SuiModule/SuiModule.svelte:1020-1055

Data Flow

The following diagram illustrates the flow from initial wallet detection to the final, customized list ready for display.

This diagram shows that detectWalletAdapters and getAvailableWallets produce a raw list, which is then processed by applyWalletConfig using the walletConfig prop before being sent to the ConnectModal.

Sources: src/lib/SuiModule/SuiModule.svelte:1057-1114

applyWalletConfig Function

This internal function is responsible for executing the customization logic.

1. Apply Custom Names: It iterates through the wallets and replaces their displayName with the value from walletConfig.customNames if a match is found. The original name is preserved in originalName.
2. Apply Ordering: It then sorts the list.
   • If a wallet's original name is present in the walletConfig.ordering array, its position is determined by its index in that array.
   • If two wallets are in the ordering array, they are sorted relative to each other.
   • If a wallet is in the array and another is not, the one in the array comes first.
   • If neither wallet is in the ordering array, they are sorted alphabetically by their original name.

Sources: src/lib/SuiModule/SuiModule.svelte:1022-1055

Relevant Data Structures

The customization process relies on two key data structures: WalletConfig and WalletWithStatus.

The WalletConfig object provides the rules for customizing a list of WalletWithStatus objects.

Sources: src/lib/SuiModule/types.ts:90-93, 112-120

WalletWithStatus Interface

This interface extends the standard wallet type with additional metadata used for rendering and sorting within the kit.

Property	Type	Description
name	string	The original detected name of the wallet. Used as the key for lookups.
displayName	string	The name to be displayed in the UI. Defaults to name but can be overridden.
originalName	string	A backup of the original name, set when a displayName is applied.
installed	boolean	A flag indicating if the wallet extension is detected in the browser.

Sources: src/lib/SuiModule/types.ts:112-120, src/lib/ConnectModal/ConnectModal.svelte:68

Display in ConnectModal

The final, processed list of WalletWithStatus objects is passed to the ConnectModal component via its availableWallets prop. The modal then renders the list, using the displayName for the wallet's name and separating wallets into "Detected" and "More" sections based on the installed status.

<!-- src/lib/ConnectModal/ConnectModal.svelte:200-209 -->
{#each detectedWallets as wallet (wallet.name)}
    <button class="wallet-button" onclick={() => onSelected(wallet)}>
        <img
            src={wallet.iconUrl}
            alt={getWalletDisplayName(wallet)}
            class="wallet-icon"
        />
        <div class="wallet-info">
            <div class="wallet-name">{getWalletDisplayName(wallet)}</div>
        </div>
        <!-- ... -->
    </button>
{/each}

The getWalletDisplayName helper function prioritizes displayName over name, ensuring custom names are shown.

Sources: src/lib/ConnectModal/ConnectModal.svelte:16, 67-68, 200-209

Conclusion

The walletConfig prop offers a straightforward API for developers to customize the wallet connection experience. By using the customNames and ordering properties, developers can re-brand and prioritize wallets in the connection modal, aligning the component's presentation with their dApp's specific needs or partnerships and improving usability for their target audience.

Sources: README.md:35-37