Themes

This guide covers the theme system in your MkSaaS website, how to switch between built-in themes, and how to create and customize your own themes.

Core Features

The MkSaaS template comes with a built-in theme system that allows users to customize the appearance of the website. The theme system includes:

• Light and dark mode support
• Multiple color themes (default, neutral, blue, green, amber)
• Theme switching functionality for users online
• Theme configuration persistence

Built-in Themes

The template includes several pre-configured themes that you can use out of the box.

• Default: The main theme with a balanced color palette
• Neutral: A grayscale theme with neutral colors
• Blue: A theme with blue as the primary color
• Green: A theme with green as the primary color
• Amber: A theme with amber as the primary color

Each theme changes the primary color and related colors while maintaining the overall design system.

Theme Configuration

The theme system is configured in the website.tsx configuration file.

export const websiteConfig: WebsiteConfig = {
  metadata: {
    theme: {
      defaultTheme: 'default', // Choose from: default, blue, green, amber, neutral
      enableSwitch: true,      // Enable/disable theme switching
    },
    // ...other configuration
  },
  // ...rest of config
};

Configuration Options:

Creating Custom Themes

You can create your own custom themes by adding new theme definitions to the global CSS file.

1. Add a New Theme Class

Add a new theme class to src/styles/globals.css:

.theme-custom {
  --primary: var(--color-purple-600);
  --primary-foreground: var(--color-purple-50);

  @variant dark {
    --primary: var(--color-purple-500);
    --primary-foreground: var(--color-purple-50);
  }
}

2. Add the Theme to the Selector

Modify the ThemeSelector component in src/components/layout/theme-selector.tsx to include your new theme:

const DEFAULT_THEMES = [
  {
    name: t('default'),
    value: 'default',
  },
  // ...existing themes
  {
    name: t('custom'),
    value: 'custom',
  },
];

3. Add the Translation Key

Add a new translation key for your theme in your translation files.

{
  "Common": {
    "theme": {
      "custom": "Custom Theme"
    }
  }
}

{
  "Common": {
    "theme": {
      "custom": "自定义主题"
    }
  }
}

Advanced Customization

For more advanced theme customization, you can modify the base theme variables.

Customizing the Base Theme

The base theme variables are defined in the :root selector in src/styles/globals.css. You can modify these variables to change the default appearance across all themes:

:root {
  --radius: 0.5rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.141 0.005 285.823);
  /* Modify other variables as needed */
}

.dark {
  --background: oklch(0.141 0.005 285.823);
  --foreground: oklch(0.985 0 0);
  /* Modify dark mode variables as needed */
}

Creating a Custom Color Palette

You can create a completely custom color palette by overriding all color variables in your theme class:

.theme-custom {
  --background: oklch(0.98 0.01 280);
  --foreground: oklch(0.2 0.01 280);
  --card: oklch(0.97 0.01 280);
  --card-foreground: oklch(0.2 0.01 280);
  /* Override all other color variables */
}

Theme Generators

You can use the following theme generators to create your own custom themes, and then copy the CSS variables to your globals.css file or use shadcn cli to add and change your globals.css file:

pnpm dlx shadcn@latest add https://tweakcn.com/r/themes/twitter.json

• shadcn/ui Theme Generator
• tweakcn Theme Generator
• ui.pub Theme Generator

Video tutorial:

This screenshot shows the default theme is now the custom theme.

FAQ

Theme Not Applying Correctly

If your theme is not applying correctly:

1. Check that the theme class is correctly defined in globals.css
2. Verify that the theme selector is enabled in website configuration
3. Check browser console for any JavaScript errors
4. Clear browser cookies and reload the page

Custom Theme Flashing on Page Load

If you see a flash of the default theme before your custom theme loads:

1. Set your custom theme as the default theme in website.tsx
2. Use a loading state or skeleton UI while the theme loads

Best Practices

• Color Contrast: Ensure that text colors have sufficient contrast with background colors for accessibility
• Test Both Modes: Always test your themes in both light and dark modes
• Limit Theme Options: Offer a small selection of well-designed themes rather than many similar options
• Theme Consistency: Maintain consistent styling across different themes to avoid UI surprises

Video Tutorial

Next Steps

Now that you understand how to work with themes in MkSaaS, explore these related topics: