> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MainWP Dashboard Themes

> Learn how MainWP Dashboard Light and Dark themes work, when quick switching appears, and how to manage legacy or custom theme selection.

MainWP Dashboard themes control the appearance of your **MainWP Dashboard** interface only.
They do not control WordPress themes on your Child Sites.

For Child Site themes, see [Manage Themes](/sites/themes/managing-themes-with-mainwp).

## What You'll Learn

* When the header uses quick Light/Dark switching
* When the header opens the theme selection modal
* How to manage theme selection from MainWP Tools
* How OS mode detection works in Quick Setup
* Where custom theme files are stored

## Prerequisites

* Access to your MainWP Dashboard admin area
* FTP or file manager access (for custom themes only)

***

## Quick Light and Dark Switching

<Steps>
  <Step title="Open your Dashboard">
    Navigate to your MainWP Dashboard.
  </Step>

  <Step title="Use the header theme switcher">
    Use the top-right header theme button:

    * Moon icon switches to Dark mode.
    * Sun icon switches to Light mode.
  </Step>

  <Step title="Confirm the new mode">
    The Dashboard reloads and applies the selected mode for your user account.
  </Step>
</Steps>

<img src="https://mintcdn.com/mainwp/WmCf2oJ6qFP5ANTT/images/customization/themes-switcher.png?fit=max&auto=format&n=WmCf2oJ6qFP5ANTT&q=85&s=9fe1fe2ba315ea5acef72f611239d575" alt="MainWP Dashboard theme switcher showing light and dark toggle behavior" width="603" height="108" data-path="images/customization/themes-switcher.png" />

MainWP uses quick switching when all of the following are true:

* Your selected theme is `default` (Light) or `default-dark` (Dark).
* No custom theme files are detected in the uploads themes directory.

Under this path, MainWP switches by writing `mainwp_quick_theme_change` in the URL and saving your user preference as `default` or `default-dark`.

***

## When the Theme Modal Appears

The header shows a palette icon and opens the **Select MainWP Theme** modal when quick switching is not used.

Common cases:

* You have one or more custom theme files.
* You are on a legacy/custom theme path.

In this modal flow, select the desired theme and save settings.

***

## Manage Themes from MainWP Tools

The **MainWP > Settings > Tools** page always includes **Select MainWP Dashboard theme**.

<img src="https://mintcdn.com/mainwp/vKWgvpW6jikCqfP0/images/dashboard/tools-page.png?fit=max&auto=format&n=vKWgvpW6jikCqfP0&q=85&s=bd91eee081ec8153ceba631b0d44ff5e" alt="MainWP Tools section showing theme selection and various utility options" width="1915" height="1357" data-path="images/dashboard/tools-page.png" />

<Steps>
  <Step title="Go to MainWP Tools">
    Navigate to **MainWP > Settings > Tools**.
  </Step>

  <Step title="Open Select MainWP Dashboard theme">
    Use the theme dropdown in the Tools section.
  </Step>

  <Step title="Choose a theme">
    Light and Dark are always available.

    Legacy options appear when currently selected. Custom `.css` theme files in uploads are also listed.
  </Step>

  <Step title="Save your settings">
    Click **Save Settings**.
  </Step>
</Steps>

***

## OS Preference Detection

MainWP does not continuously auto-sync theme mode with your operating system.

During Quick Setup, MainWP can detect OS color preference and save an initial Light/Dark selection when:

* Your user has no saved MainWP theme preference.
* The Quick Setup flow condition for an empty connected-sites state applies.

After a theme is saved for your user, that saved preference is used until you change it.

***

## Custom Theme Files

You can create custom themes by modifying existing CSS files and uploading them to your Dashboard site.

<Steps>
  <Step title="Download the MainWP Dashboard plugin">
    Download the **MainWP Dashboard** plugin from the [WordPress.org repository](https://wordpress.org/plugins/mainwp/).
  </Step>

  <Step title="Extract the plugin files">
    Unzip the plugin files to your computer.
  </Step>

  <Step title="Find the default themes">
    Navigate to `/mainwp/assets/css/themes` directory to find the built-in theme CSS files.
  </Step>

  <Step title="Copy and customize a theme">
    Copy one of the CSS files and open it in your preferred code editor. Make your customizations.
  </Step>

  <Step title="Rename your theme file">
    Save the file with a new descriptive name (e.g., `my-agency-theme.css`).
  </Step>

  <Step title="Upload to your Dashboard">
    Upload the CSS file to `/wp-content/uploads/mainwp/themes/` on your Dashboard site using FTP or your hosting file manager.
  </Step>

  <Step title="Select your custom theme">
    Your custom theme appears in the theme selector in **MainWP > Settings > Tools** and in the theme modal path.
  </Step>
</Steps>

***

## Theme File Locations

| Location                                        | Purpose                           |
| ----------------------------------------------- | --------------------------------- |
| `/wp-content/plugins/mainwp/assets/css/themes/` | Built-in themes (do not modify)   |
| `/wp-content/uploads/mainwp/themes/`            | Custom themes (upload yours here) |

<Note>
  If an older `custom-dashboard` folder exists, MainWP migrates it to the `themes` folder path used now.

  Custom themes in the uploads directory persist through plugin updates. Built-in themes may be overwritten during updates.
</Note>

***

## Legacy Theme Compatibility

* Legacy theme options remain supported for users already on those themes.
* If legacy/custom conditions are detected, the header uses the palette button (modal path) instead of direct Light/Dark toggle.
* For the default experience, use Light or Dark themes.

***

## Self-Check Checklist

* [ ] This page is used for MainWP Dashboard appearance, not Child Site themes
* [ ] Header shows moon/sun quick switcher when using default Light/Dark with no custom theme files
* [ ] Header shows palette button and modal path for legacy/custom scenarios
* [ ] MainWP Tools includes **Select MainWP Dashboard theme**
* [ ] Theme preference persists for your user after reload

***

## Related Resources

* [Change Sidebar Position](/customization/how-to-change-the-sidebar-position) - Adjust sidebar location
* [Customize Dashboard Logo](/customization/customize-mainwp-dashboard-logo) - Brand your Dashboard
* [Widget Column Layout](/customization/how-can-i-change-the-number-of-widget-columns-on-the-overview-page) - Adjust widget arrangement
* [Manage Themes](/sites/themes/managing-themes-with-mainwp) - Manage Child Site WordPress themes