From c6daf4fe0cd88ccb4d6efed275521650fd718cba Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Tue, 9 Dec 2025 16:15:34 -0500
Subject: [PATCH] feat(clerk-js,types): Add WalletInitialIcon component and
 update element descriptors for Web3 wallet buttons

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 .../src/ui/common/WalletInitialIcon.tsx       | 43 +++++++++++++++++++
 .../ui/customizables/elementDescriptors.ts    | 11 +++++
 .../ui/elements/Web3SolanaWalletButtons.tsx   |  9 ++--
 packages/shared/src/types/appearance.ts       | 11 +++++
 4 files changed, 71 insertions(+), 3 deletions(-)
 create mode 100644 packages/clerk-js/src/ui/common/WalletInitialIcon.tsx

diff --git a/packages/clerk-js/src/ui/common/WalletInitialIcon.tsx b/packages/clerk-js/src/ui/common/WalletInitialIcon.tsx
new file mode 100644
index 00000000000..362a9f64312
--- /dev/null
+++ b/packages/clerk-js/src/ui/common/WalletInitialIcon.tsx
@@ -0,0 +1,43 @@
+import { Box, descriptors, Text } from '../customizables';
+import type { PropsOfComponent } from '../styledSystem';
+import { common } from '../styledSystem';
+
+type WalletInitialIconProps = PropsOfComponent<typeof Box> & {
+  value: string;
+  /**
+   * The wallet provider name
+   */
+  id: string;
+};
+
+export const WalletInitialIcon = (props: WalletInitialIconProps) => {
+  const { value, id, ...rest } = props;
+
+  return (
+    <Box
+      as='span'
+      elementDescriptor={[descriptors.walletIcon, descriptors.web3WalletButtonsWalletInitialIcon]}
+      elementId={descriptors.web3WalletButtonsWalletInitialIcon.setId(id)}
+      sx={t => ({
+        ...common.centeredFlex('inline-flex'),
+        width: t.space.$4,
+        height: t.space.$4,
+        borderRadius: t.radii.$sm,
+        color: t.colors.$colorPrimaryForeground,
+        backgroundColor: t.colors.$primary500,
+      })}
+      {...rest}
+    >
+      <Text
+        as='span'
+        variant='buttonSmall'
+        sx={{
+          ...common.centeredFlex('inline-flex'),
+          width: '100%',
+        }}
+      >
+        {value[0].toUpperCase()}
+      </Text>
+    </Box>
+  );
+};
diff --git a/packages/clerk-js/src/ui/customizables/elementDescriptors.ts b/packages/clerk-js/src/ui/customizables/elementDescriptors.ts
index 9d0dfae51dc..f302c79941b 100644
--- a/packages/clerk-js/src/ui/customizables/elementDescriptors.ts
+++ b/packages/clerk-js/src/ui/customizables/elementDescriptors.ts
@@ -515,6 +515,17 @@ export const APPEARANCE_KEYS = containsAllElementsConfigKeys([
   'enterpriseConnectionsRoot',
   'enterpriseConnectionButton',
   'enterpriseConnectionButtonText',
+
+  'web3WalletButtonsRoot',
+  'web3WalletButtons',
+  'web3WalletButtonsIconButton',
+  'web3WalletButtonsBlockButton',
+  'web3WalletButtonsBlockButtonText',
+  'web3WalletButtonsWalletIcon',
+  'web3WalletButtonsWalletInitialIcon',
+
+  'walletIcon',
+  'walletInitialIcon',
 ] as const).map(camelize) as (keyof ElementsConfig)[];
 
 type TargettableClassname<K extends keyof ElementsConfig> = `${typeof CLASS_PREFIX}${K}`;
diff --git a/packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx b/packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx
index a780ee54714..4ca1f61e226 100644
--- a/packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx
+++ b/packages/clerk-js/src/ui/elements/Web3SolanaWalletButtons.tsx
@@ -4,7 +4,7 @@ import { MAINNET_ENDPOINT } from '@solana/wallet-standard';
 import type { Ref } from 'react';
 import React, { forwardRef, isValidElement, useMemo } from 'react';
 
-import { ProviderInitialIcon } from '@/ui/common';
+import { WalletInitialIcon } from '@/ui/common/WalletInitialIcon';
 import {
   Button,
   descriptors,
@@ -94,6 +94,7 @@ const Web3SolanaWalletButtonsInner = ({ web3AuthCallback }: Web3WalletButtonsPro
     <Flex
       direction='col'
       gap={2}
+      elementDescriptor={descriptors.web3WalletButtonsRoot}
     >
       {strategyRows.map((row, rowIndex) => (
         <Grid
@@ -102,6 +103,7 @@ const Web3SolanaWalletButtonsInner = ({ web3AuthCallback }: Web3WalletButtonsPro
               return r.name;
             })
             .join('-')}
+          elementDescriptor={descriptors.web3WalletButtons}
           gap={2}
           sx={t => ({
             justifyContent: 'center',
@@ -130,6 +132,7 @@ const Web3SolanaWalletButtonsInner = ({ web3AuthCallback }: Web3WalletButtonsPro
 
             const imageOrInitial = w.icon ? (
               <Image
+                elementDescriptor={[descriptors.walletIcon, descriptors.web3WalletButtonsWalletInitialIcon]}
                 isDisabled={card.isLoading}
                 isLoading={card.loadingMetadata === w.name}
                 src={w.icon}
@@ -137,10 +140,10 @@ const Web3SolanaWalletButtonsInner = ({ web3AuthCallback }: Web3WalletButtonsPro
                 sx={theme => ({ width: theme.sizes.$4, height: 'auto', maxWidth: '100%' })}
               />
             ) : (
-              <ProviderInitialIcon
+              <WalletInitialIcon
                 value={w.name}
                 isDisabled={card.isLoading}
-                id={'linear'}
+                id={w.name}
               />
             );
 
diff --git a/packages/shared/src/types/appearance.ts b/packages/shared/src/types/appearance.ts
index 809aae80217..739ecd36fe7 100644
--- a/packages/shared/src/types/appearance.ts
+++ b/packages/shared/src/types/appearance.ts
@@ -650,6 +650,17 @@ export type ElementsConfig = {
   enterpriseConnectionsRoot: WithOptions;
   enterpriseConnectionButton: WithOptions;
   enterpriseConnectionButtonText: WithOptions;
+
+  web3WalletButtonsRoot: WithOptions;
+  web3WalletButtons: WithOptions;
+  web3WalletButtonsIconButton: WithOptions<string, LoadingState>;
+  web3WalletButtonsBlockButton: WithOptions<string, LoadingState>;
+  web3WalletButtonsBlockButtonText: WithOptions<string>;
+  web3WalletButtonsWalletIcon: WithOptions<string, LoadingState>;
+  web3WalletButtonsWalletInitialIcon: WithOptions<string, LoadingState>;
+
+  walletIcon: WithOptions<string, LoadingState>;
+  walletInitialIcon: WithOptions<string, LoadingState>;
 };
 
 export type Elements = {