feat: Add custom themes (#1465)

playground/nextjs-app-router/app/globals.css

@@ -59,18 +59,92 @@
   }
 }
 
-/* Customize Theme */
-/*
-@layer base {
+/* Customize existing Theme */
+
+/* @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*/
+/* 
+Usage: 
+  config={{
+    appearance: {
+      mode: 'auto',
+      theme: 'custom',
+    },
+  }}
+
+  config={{
+    appearance: {
+      mode: 'light', // To use custom-light only.
+      theme: 'custom',
+    },
+  }}
+*/
+.custom-light {
+  --ock-bg-primary: red;
+}
+
+.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-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 {
   * {

playground/nextjs-app-router/components/form/component-theme.tsx

@@ -29,6 +29,7 @@ export function ComponentTheme() {
           <SelectItem value="base">Base</SelectItem>
           <SelectItem value="cyberpunk">Cyberpunk</SelectItem>
           <SelectItem value="hacker">Hacker</SelectItem>
+          <SelectItem value="custom">Custom</SelectItem>
         </SelectContent>
       </Select>
     </div>

site/docs/pages/guides/themes.mdx

@@ -25,6 +25,7 @@ OnchainKit offers multiple themes to quickly style your components. Set the them
 - `base`: Single mode only.
 - `cyberpunk`: Single mode only.
 - `hacker`: Single mode only.
+- `custom`: Single mode only.
 
 If no theme is selected, the **`default`** theme is applied automatically.
 
@@ -60,15 +61,16 @@ 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'
+      theme: 'default', // 'default' | 'base' | 'cyberpunk' | 'hacker' | 'your-custom-theme'
     },
   }}
 >
 ```
 
 ## CSS Overrides
 
-You can further customize the appearance by overriding CSS styles. This allows for fine-tuning the look of individual components beyond the provided themes.
+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 {
@@ -78,9 +80,69 @@ You can further customize the appearance by overriding CSS styles. This allows f
   .base,
   .cyberpunk, 
   .hacker {
+    /* Override specific variables as needed */
+    --ock-font-family: 'your-custom-value';
+    --ock-border-radius: 'your-custom-value';
+    --ock-text-primary: 'your-custom-value';
+  }
+}
+```
+
+## Custom Theme
+
+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-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';
@@ -90,6 +152,7 @@ You can further customize the appearance by overriding CSS styles. This allows f
     --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';
@@ -112,6 +175,7 @@ You can further customize the appearance by overriding CSS styles. This allows f
     --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';
@@ -120,10 +184,15 @@ You can further customize the appearance by overriding CSS styles. This allows f
     --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 */
+  }
 }
 ```

src/types.ts

@@ -21,7 +21,12 @@ export type isEthereumOptions = {
 export type Mode = 'auto' | 'light' | 'dark';
 
 // External theme options for users
-export type ComponentTheme = 'base' | 'cyberpunk' | 'default' | 'hacker';
+export type ComponentTheme =
+  | 'base'
+  | 'cyberpunk'
+  | 'default'
+  | 'hacker'
+  | string;
 
 // Internal theme options, including light/dark variants for 'default'
 export type UseThemeReact =
@@ -30,7 +35,8 @@ export type UseThemeReact =
   | 'default'
   | 'hacker'
   | 'default-light'
-  | 'default-dark';
+  | 'default-dark'
+  | string;
 
 /**
  * Note: exported as public Type