diff --git a/playground/nextjs-app-router/app/globals.css b/playground/nextjs-app-router/app/globals.css
index 7b25fa8ecc..fb60fe5d76 100644
--- a/playground/nextjs-app-router/app/globals.css
+++ b/playground/nextjs-app-router/app/globals.css
@@ -60,68 +60,90 @@
 }
 
 /* Customize existing Theme */
-/*
-@layer base {
+
+/* @layer base {
   :root,
   .default-light,
   .default-dark,
   .base,
   .cyberpunk,
   .hacker {
-    --ock-bg-primary: red;
-  }
-} */
+    /* Override specific variables as needed */
+    /* --ock-font-family: 'your-custom-value';
+    --ock-border-radius: 'your-custom-value';
+    --ock-text-primary: 'your-custom-value'; */
+  /* }
+}  */ 
+
 
 /* Create your own custom Theme*/
-@layer base {
-  .custom {
-    --ock-font-family: 'DM Sans', sans-serif;
-    --ock-border-radius: 0.5rem;
-    --ock-border-radius-inner: 0.25rem;
-    --ock-text-inverse: #f9fafb;
-    --ock-text-foreground: #030712;
-    --ock-text-foreground-muted: #4b5563;
-    --ock-text-error: #374151;
-    --ock-text-primary: #1f2937;
-    --ock-text-success: #4b5563;
-    --ock-text-warning: #374151;
-    --ock-text-disabled: #9ca3af;
+/* 
+Usage: 
+  config={{
+    appearance: {
+      mode: 'auto',
+      theme: 'custom',
+    },
+  }}
 
-    --ock-bg-default: #f9fafb;
-    --ock-bg-default-hover: #e5e7eb;
-    --ock-bg-default-active: #d1d5db;
-    --ock-bg-alternate: #e5e7eb;
-    --ock-bg-alternate-hover: #d1d5db;
-    --ock-bg-alternate-active: #9ca3af;
-    --ock-bg-inverse: #f3f4f6;
-    --ock-bg-inverse-hover: #e5e7eb;
-    --ock-bg-inverse-active: #d1d5db;
-    --ock-bg-primary: #4b5563;
-    --ock-bg-primary-hover: #374151;
-    --ock-bg-primary-active: #1f2937;
-    --ock-bg-primary-washed: #f3f4f6;
-    --ock-bg-primary-disabled: #d1d5db;
-    --ock-bg-secondary: #e5e7eb;
-    --ock-bg-secondary-hover: #d1d5db;
-    --ock-bg-secondary-active: #9ca3af;
-    --ock-bg-error: #4b5563;
-    --ock-bg-warning: #6b7280;
-    --ock-bg-success: #9ca3af;
-    --ock-bg-default-reverse: #030712;
+  config={{
+    appearance: {
+      mode: 'light', // To use custom-light only.
+      theme: 'custom',
+    },
+  }}
+*/
+.custom-light {
+  --ock-bg-primary: red;
+}
 
-    --ock-icon-color-primary: #4b5563;
-    --ock-icon-color-foreground: #030712;
-    --ock-icon-color-foreground-muted: #4b5563;
-    --ock-icon-color-inverse: #f9fafb;
-    --ock-icon-color-error: #374151;
-    --ock-icon-color-success: #4b5563;
-    --ock-icon-color-warning: #374151;
+.custom-dark {
+  --ock-font-family: 'DM Sans', sans-serif;
+  --ock-border-radius: 0.5rem;
+  --ock-border-radius-inner: 0.25rem;
+  --ock-text-inverse: #1f2937;
+  --ock-text-foreground: #f9fafb;
+  --ock-text-foreground-muted: #9ca3af;
+  --ock-text-error: #d1d5db;
+  --ock-text-primary: #f3f4f6;
+  --ock-text-success: #9ca3af;
+  --ock-text-warning: #d1d5db;
+  --ock-text-disabled: #4b5563;
 
-    --ock-line-primary: #4b5563;
-    --ock-line-default: #d1d5db;
-    --ock-line-heavy: #6b7280;
-    --ock-line-inverse: #374151;
-  }
+  --ock-bg-default: #111827;
+  --ock-bg-default-hover: #1f2937;
+  --ock-bg-default-active: #374151;
+  --ock-bg-alternate: #1f2937;
+  --ock-bg-alternate-hover: #374151;
+  --ock-bg-alternate-active: #4b5563;
+  --ock-bg-inverse: #0f172a;
+  --ock-bg-inverse-hover: #1e293b;
+  --ock-bg-inverse-active: #334155;
+  --ock-bg-primary: green;
+  --ock-bg-primary-hover: #6b7280;
+  --ock-bg-primary-active: #9ca3af;
+  --ock-bg-primary-washed: #1f2937;
+  --ock-bg-primary-disabled: #374151;
+  --ock-bg-secondary: #1f2937;
+  --ock-bg-secondary-hover: #374151;
+  --ock-bg-secondary-active: #4b5563;
+  --ock-bg-error: #991b1b;
+  --ock-bg-warning: #92400e;
+  --ock-bg-success: #065f46;
+  --ock-bg-default-reverse: #f9fafb;
+
+  --ock-icon-color-primary: #9ca3af;
+  --ock-icon-color-foreground: #f9fafb;
+  --ock-icon-color-foreground-muted: #9ca3af;
+  --ock-icon-color-inverse: #1f2937;
+  --ock-icon-color-error: #f87171;
+  --ock-icon-color-success: #34d399;
+  --ock-icon-color-warning: #fbbf24;
+
+  --ock-line-primary: #6b7280;
+  --ock-line-default: #374151;
+  --ock-line-heavy: #4b5563;
+  --ock-line-inverse: #e5e7eb;
 }
 
 @layer base {
diff --git a/playground/nextjs-app-router/components/AppProvider.tsx b/playground/nextjs-app-router/components/AppProvider.tsx
index 4983eab8cd..1d146924c5 100644
--- a/playground/nextjs-app-router/components/AppProvider.tsx
+++ b/playground/nextjs-app-router/components/AppProvider.tsx
@@ -35,7 +35,6 @@ export type ComponentTheme =
   | 'cyberpunk'
   | 'default'
   | 'hacker'
-  | 'custom'
   | 'none'; // Simulates an undefined theme field
 
 export type ComponentMode = 'auto' | 'light' | 'dark';
diff --git a/playground/nextjs-app-router/onchainkit/package.json b/playground/nextjs-app-router/onchainkit/package.json
index 2a0d537e14..c97ff0ecb1 100644
--- a/playground/nextjs-app-router/onchainkit/package.json
+++ b/playground/nextjs-app-router/onchainkit/package.json
@@ -119,12 +119,6 @@
       "import": "./esm/api/index.js",
       "default": "./esm/api/index.js"
     },
-    "./checkout": {
-      "types": "./esm/checkout/index.d.ts",
-      "module": "./esm/checkout/index.js",
-      "import": "./esm/checkout/index.js",
-      "default": "./esm/checkout/index.js"
-    },
     "./core": {
       "types": "./esm/core/index.d.ts",
       "module": "./esm/core/index.js",
@@ -155,6 +149,12 @@
       "import": "./esm/identity/index.js",
       "default": "./esm/identity/index.js"
     },
+    "./pay": {
+      "types": "./esm/pay/index.d.ts",
+      "module": "./esm/pay/index.js",
+      "import": "./esm/pay/index.js",
+      "default": "./esm/pay/index.js"
+    },
     "./swap": {
       "types": "./esm/swap/index.d.ts",
       "module": "./esm/swap/index.js",
diff --git a/playground/nextjs-app-router/package.json b/playground/nextjs-app-router/package.json
index c1126a85be..615d61c9e4 100644
--- a/playground/nextjs-app-router/package.json
+++ b/playground/nextjs-app-router/package.json
@@ -14,6 +14,7 @@
     "lint": "next lint"
   },
   "dependencies": {
+    "@coinbase/onchainkit": "^0.34.0",
     "@radix-ui/react-dropdown-menu": "^2.1.1",
     "@radix-ui/react-icons": "^1.3.0",
     "@radix-ui/react-label": "^2.1.0",
diff --git a/site/docs/pages/guides/themes.mdx b/site/docs/pages/guides/themes.mdx
index 988edbf205..ae496f1ef0 100644
--- a/site/docs/pages/guides/themes.mdx
+++ b/site/docs/pages/guides/themes.mdx
@@ -37,7 +37,7 @@ If no theme is selected, the **`default`** theme is applied automatically.
   config={{ // [!code focus]
     appearance: { // [!code focus]
       mode: 'auto', // 'auto' | 'light' | 'dark'
-      theme: 'default', // 'default' | 'base' | 'cyberpunk' | 'hacker' | 'custom' // [!code focus]
+      theme: 'default', // 'default' | 'base' | 'cyberpunk' | 'hacker' // [!code focus]
     }, // [!code focus]
   }} // [!code focus]
 >
@@ -61,7 +61,7 @@ If no mode is specified, `auto` mode will be applied by default.
   config={{
     appearance: {
       mode: 'auto', // 'auto' | 'light' | 'dark' // [!code focus]
-      theme: 'default', // 'default' | 'base' | 'cyberpunk' | 'hacker' | 'custom'
+      theme: 'default', // 'default' | 'base' | 'cyberpunk' | 'hacker' | 'your-custom-theme'
     },
   }}
 >
@@ -69,8 +69,8 @@ If no mode is specified, `auto` mode will be applied by default.
 
 ## CSS Overrides
 
-CSS Overrides allow you to fine-tune specific aspects of an existing theme. 
-This is useful when you want to make minor adjustments to the appearance of individual components without creating an entirely new theme.
+Fine-tune specific aspects of an existing theme. 
+This is useful when you want to make adjustments to the appearance of the components without creating an entirely new theme.
 
 ```css
 @layer base {
@@ -88,19 +88,61 @@ This is useful when you want to make minor adjustments to the appearance of indi
 }
 ```
 
-
 ## Custom Theme
 
-Creating a custom theme allows you to define an entirely new look and feel for your application. 
+Define an entirely new look and feel for your application. 
 This gives you complete control over all aspects of the design, including colors, fonts, and other visual properties.
 
+#### Usage Options:
+
+##### Automatic Light/Dark Mode Switching:
+- To automatically switch between light and dark versions of your custom theme:
+
+```tsx twoslash
+// @noErrors:  2304 17008 1005
+<OnchainKitProvider
+  apiKey={process.env.NEXT_PUBLIC_ONCHAINKIT_API_KEY}
+  chain={base}
+  config={{
+    appearance: {
+      mode: 'auto', // [!code focus]
+      theme: 'custom', // [!code focus]
+    },
+  }}
+>
+```
+
+##### Single Theme Version:
+- To use only one version of your custom theme at all times:
+
+```tsx twoslash
+// @noErrors:  2304 17008 1005
+<OnchainKitProvider
+  apiKey={process.env.NEXT_PUBLIC_ONCHAINKIT_API_KEY}
+  chain={base}
+  config={{
+    appearance: {
+      mode: 'light', // [!code focus]
+      theme: 'custom', // [!code focus]
+    },
+  }} 
+>
+```
+
+##### Defining a custom theme
+
+Use CSS variables to define your custom theme. 
+The class name definitions must include the `-light` or `-dark` suffix.
 
 ```css
 @layer base {
-  .custom {
+  .custom-light {
+    /* Font and Shape */
     --ock-font-family: 'your-custom-value';
     --ock-border-radius: 'your-custom-value';
     --ock-border-radius-inner: 'your-custom-value';
+
+    /* Text Colors */
     --ock-text-inverse: 'your-custom-value';
     --ock-text-foreground: 'your-custom-value';
     --ock-text-foreground-muted: 'your-custom-value';
@@ -110,6 +152,7 @@ This gives you complete control over all aspects of the design, including colors
     --ock-text-warning: 'your-custom-value';
     --ock-text-disabled: 'your-custom-value';
 
+    /* Background Colors */
     --ock-bg-default: 'your-custom-value';
     --ock-bg-default-hover: 'your-custom-value';
     --ock-bg-default-active: 'your-custom-value';
@@ -132,6 +175,7 @@ This gives you complete control over all aspects of the design, including colors
     --ock-bg-success: 'your-custom-value';
     --ock-bg-default-reverse: 'your-custom-value';
 
+    /* Icon Colors */
     --ock-icon-color-primary: 'your-custom-value';
     --ock-icon-color-foreground: 'your-custom-value';
     --ock-icon-color-foreground-muted: 'your-custom-value';
@@ -140,10 +184,15 @@ This gives you complete control over all aspects of the design, including colors
     --ock-icon-color-success: 'your-custom-value';
     --ock-icon-color-warning: 'your-custom-value';
 
+    /* Line Colors */
     --ock-line-primary: 'your-custom-value';
     --ock-line-default: 'your-custom-value';
     --ock-line-heavy: 'your-custom-value';
     --ock-line-inverse: 'your-custom-value';
   }
+
+  .custom-dark {
+    /* Define dark mode custom classes here */
+  }
 }
 ```
diff --git a/src/styles/tailwind-base.css b/src/styles/tailwind-base.css
index 45bfc391c3..1139a9b23f 100644
--- a/src/styles/tailwind-base.css
+++ b/src/styles/tailwind-base.css
@@ -248,55 +248,6 @@
     --ock-line-heavy: theme(colors.zinc.500);
     --ock-line-inverse: theme(colors.zinc.700);
   }
-
-  .custom {
-    --ock-font-family: 'DM Sans', sans-serif;
-    --ock-border-radius: 0.5rem;
-    --ock-border-radius-inner: 0.25rem;
-    --ock-text-inverse: theme(colors.gray.50);
-    --ock-text-foreground: theme(colors.gray.950);
-    --ock-text-foreground-muted: theme(colors.gray.600);
-    --ock-text-error: theme(colors.gray.700);
-    --ock-text-primary: theme(colors.gray.800);
-    --ock-text-success: theme(colors.gray.600);
-    --ock-text-warning: theme(colors.gray.700);
-    --ock-text-disabled: theme(colors.gray.400);
-
-    --ock-bg-default: theme(colors.gray.50);
-    --ock-bg-default-hover: theme(colors.gray.200);
-    --ock-bg-default-active: theme(colors.gray.300);
-    --ock-bg-alternate: theme(colors.gray.200);
-    --ock-bg-alternate-hover: theme(colors.gray.300);
-    --ock-bg-alternate-active: theme(colors.gray.400);
-    --ock-bg-inverse: theme(colors.gray.100);
-    --ock-bg-inverse-hover: theme(colors.gray.200);
-    --ock-bg-inverse-active: theme(colors.gray.300);
-    --ock-bg-primary: theme(colors.gray.600);
-    --ock-bg-primary-hover: theme(colors.gray.700);
-    --ock-bg-primary-active: theme(colors.gray.800);
-    --ock-bg-primary-washed: theme(colors.gray.100);
-    --ock-bg-primary-disabled: theme(colors.gray.300);
-    --ock-bg-secondary: theme(colors.gray.200);
-    --ock-bg-secondary-hover: theme(colors.gray.300);
-    --ock-bg-secondary-active: theme(colors.gray.400);
-    --ock-bg-error: theme(colors.gray.600);
-    --ock-bg-warning: theme(colors.gray.500);
-    --ock-bg-success: theme(colors.gray.400);
-    --ock-bg-default-reverse: theme(colors.gray.950);
-
-    --ock-icon-color-primary: theme(colors.gray.600);
-    --ock-icon-color-foreground: theme(colors.gray.950);
-    --ock-icon-color-foreground-muted: theme(colors.gray.600);
-    --ock-icon-color-inverse: theme(colors.gray.50);
-    --ock-icon-color-error: theme(colors.gray.700);
-    --ock-icon-color-success: theme(colors.gray.600);
-    --ock-icon-color-warning: theme(colors.gray.700);
-
-    --ock-line-primary: theme(colors.gray.600);
-    --ock-line-default: theme(colors.gray.300);
-    --ock-line-heavy: theme(colors.gray.500);
-    --ock-line-inverse: theme(colors.gray.700);
-  }
 }
 
 @tailwind utilities;
diff --git a/src/types.ts b/src/types.ts
index bd3385f0f7..61d8a30f18 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -26,7 +26,7 @@ export type ComponentTheme =
   | 'cyberpunk'
   | 'default'
   | 'hacker'
-  | 'custom';
+  | string;
 
 // Internal theme options, including light/dark variants for 'default'
 export type UseThemeReact =
@@ -34,9 +34,9 @@ export type UseThemeReact =
   | 'cyberpunk'
   | 'default'
   | 'hacker'
-  | 'custom'
   | 'default-light'
-  | 'default-dark';
+  | 'default-dark'
+  | string;
 
 /**
  * Note: exported as public Type
diff --git a/src/useTheme.test.ts b/src/useTheme.test.ts
index 01a54dd7a7..4049df701b 100644
--- a/src/useTheme.test.ts
+++ b/src/useTheme.test.ts
@@ -90,18 +90,12 @@ describe('useTheme', () => {
       'cyberpunk',
       'base',
       'hacker',
-      'custom',
       'default-light',
       'default-dark',
     ];
 
     for (const theme of allThemes) {
-      if (
-        theme === 'cyberpunk' ||
-        theme === 'base' ||
-        theme === 'hacker' ||
-        theme === 'custom'
-      ) {
+      if (theme === 'cyberpunk' || theme === 'base' || theme === 'hacker') {
         mockUseOnchainKit(theme, 'auto');
       } else {
         const [baseTheme, mode] = theme.split('-');
diff --git a/src/useTheme.ts b/src/useTheme.ts
index 2478976d0a..e2c1b3e55f 100644
--- a/src/useTheme.ts
+++ b/src/useTheme.ts
@@ -9,12 +9,7 @@ export function useTheme(): UseThemeReact {
   } = useOnchainKit();
   const { theme = 'default', mode = 'auto' } = appearance || {};
 
-  if (
-    theme === 'cyberpunk' ||
-    theme === 'base' ||
-    theme === 'hacker' ||
-    theme === 'custom'
-  ) {
+  if (theme === 'cyberpunk' || theme === 'base' || theme === 'hacker') {
     return theme;
   }