Customizing Themes and Injecting CSS in Clash Verge Rev: A Complete Guide

You can personalize Clash Verge Rev by modifying the theme_setting configuration to change colors and fonts, or by entering raw CSS into the css_injection field which gets scoped to the editor area via the useCustomTheme hook.

Clash Verge Rev provides extensive UI customization through its theme system and CSS injection capabilities. This guide examines the implementation in the clash-verge-rev/clash-verge-rev repository, showing you how to modify the source files like src/pages/_layout/hooks/use-custom-theme.ts and src/components/setting/mods/theme-viewer.tsx to achieve your desired look.

Understanding the Theme Architecture

The theming system relies on three core components working together: default theme definitions, a custom hook that applies configurations, and a UI component for user input.

Default Theme Definitions

The baseline palettes reside in src/pages/_theme.tsx. This module exports defaultTheme for light mode and defaultDarkTheme for dark mode. The dark theme extends the light palette, selectively overriding specific color values to maintain consistency while adapting to dark environments.

The useCustomTheme Hook

Located at src/pages/_layout/hooks/use-custom-theme.ts, this hook serves as the engine for theme application. It performs several critical functions:

• Detects system theme preferences using the Tauri window API when theme_mode is set to "system"
• Constructs a Material-UI theme via createTheme, merging user overrides from theme_setting with the appropriate default theme
• Injects CSS custom properties (--primary-main, --divider-color, --background-color) into document.documentElement
• Handles custom CSS injection through wrapCssInjectionWithScope, which wraps user CSS in an @scope rule when the browser supports CSS Scope, limiting styles to the editor area defined by CSS_INJECTION_SCOPE_LIMIT

Theme Viewer Component

The user interface for customization lives in src/components/setting/mods/theme-viewer.tsx. This component renders color pickers, font selectors, background image uploaders, and a textarea for css_injection. Changes trigger the setTheme method from useVerge, persisting modifications to the configuration file.

How to Customize Theme Colors and Fonts

You can modify the visual appearance by updating the theme_setting object in your Verge configuration. The following JSON structure demonstrates the available customization options:

{
  "theme_mode": "light",
  "theme_setting": {
    "primary_color": "#ff4500",
    "secondary_color": "#00bfff",
    "font_family": "Helvetica, Arial, sans-serif",
    "background_image": "https://example.com/bg.jpg",
    "background_blend_mode": "multiply",
    "background_opacity": 0.85
  }
}

Paste this configuration into the Theme section of the Settings page. The useCustomTheme hook detects these values and immediately regenerates the MUI theme with your specified palette. The font_family value overrides the default stack defined in src/pages/_theme.tsx, while background_image and related properties control the application backdrop.

Injecting Custom CSS in Clash Verge Rev

For advanced styling beyond the provided color pickers, enter raw CSS into the CSS Injection textarea. The system supports modern CSS features and automatically scopes styles to prevent interface breakage.

/* Increase proxy list row height */
.proxy-item {
  min-height: 48px;
}

/* Highlight active proxy with primary color */
[data-proxy-active="true"] .proxy-item {
  border-left: 4px solid var(--primary-main);
}

/* Customize Monaco editor tokens using CSS variables */
[data-css-injection-root] .mtk1 {
  color: var(--primary-main) !important;
}

When you save these styles, the wrapCssInjectionWithScope function in use-custom-theme.ts processes the input. If your browser supports CSS Scope, the CSS gets wrapped in an @scope block targeting CSS_INJECTION_SCOPE_LIMIT, ensuring rules only affect the editor area. Otherwise, the hook injects the CSS directly while relying on the [data-css-injection-root] attribute for scoping.

Programmatic Theme Control

Developers extending Clash Verge Rev can interact with the theme system programmatically using the ThemeViewer component and useVerge hook:

import { useVerge } from '@/hooks/use-verge';
import ThemeViewer from '@/components/setting/mods/theme-viewer';

export default function SettingsPage() {
  const { verge, setVerge } = useVerge();

  return (
    <ThemeViewer
      theme={verge?.theme_setting}
      onChange={next => setVerge({ ...verge, theme_setting: next })}
    />
  );
}

This pattern allows custom settings pages to leverage the built-in theme editor while maintaining full control over configuration persistence through the setVerge method.

Key Source Files Reference

Path	Purpose
src/pages/_theme.tsx	Default light and dark theme palettes
src/pages/_layout/hooks/use-custom-theme.ts	Core hook for theme creation, CSS variable injection, and custom CSS processing
src/components/setting/mods/theme-viewer.tsx	UI component for editing theme settings and CSS injection
src/types/global.d.ts	TypeScript definitions for IVergeConfig and theme_setting structure

Summary

• Theme customization in Clash Verge Rev centers on the theme_setting configuration object, which overrides default palettes defined in src/pages/_theme.tsx.
• CSS injection allows advanced styling through the css_injection field, automatically scoped to the editor area via wrapCssInjectionWithScope in use-custom-theme.ts.
• The useCustomTheme hook orchestrates theme application by detecting system preferences, creating MUI themes, injecting CSS variables, and processing custom styles.
• All UI controls reside in ThemeViewer (src/components/setting/mods/theme-viewer.tsx), which persists changes through the useVerge hook.

Frequently Asked Questions

How do I change the primary color in Clash Verge Rev?

Navigate to Settings > Theme and modify the Primary Color field, or edit the theme_setting.primary_color value in your configuration file. The useCustomTheme hook in src/pages/_layout/hooks/use-custom-theme.ts applies this value to the MUI theme and updates the --primary-main CSS variable immediately.

Where does custom CSS get injected in the DOM?

The useCustomTheme hook creates a <style id="verge-theme"> element and appends it to the document. If your browser supports CSS Scope, the CSS gets wrapped in an @scope rule targeting the editor container; otherwise, it injects raw CSS with scoping attributes to prevent style leakage.

Can I use system theme detection with custom colors?

Yes. Set theme_mode to "system" in your configuration. The hook queries the Tauri window API to detect OS-level theme changes and automatically switches between your custom light and dark palettes while preserving your color overrides.

What CSS variables are available for custom styling?

The hook exposes several CSS custom properties including --primary-main, --secondary-main, --background-color, --divider-color, and --font-family. You can reference these in your css_injection styles to ensure consistency with the active theme.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}