Light/dark mode toggle icon is reversed

[informatix8]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

The light/dark mode toggle icon is reversed. When in light mode, it should display a moon icon with the HTML title "Switch to dark mode"—indicating the result of clicking—rather than representing the current state.

This aligns with standard UX conventions where:

• The icon always reflects the target state (what you’ll get after clicking)
• The HTML title describes the action ("Switch to...") instead of the current mode

Reproducible demo

No response

Steps to reproduce

Standard installation

Expected behavior

• When in light mode, the mode button should display a moon icon.
• When in dark mode, the mode button should display the sun icon.

Actual behavior

• When in light mode, the mode button displays the sun icon.
• When in dark mode, the mode button displays the moon icon.

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• I'd be willing to fix this bug myself.

[slorber]

I understand your point, but can you please back up your claims that this is a standard UX convention with authoritative resources to verify that?

From what I see:

• we used this pattern for years, and nobody ever complained so far
• other websites, and docs frameworks also use this pattern (for example, https://rspress.rs/), but I agree yours is also very common and there's no clear consensus in usage
• many others implementing 3 choices use a choice dropdown instead of a 3-state toggle button, so displaying the current state makes more sense in that context

---

Before doing any change, I'd rather survey the community to be sure this is what they expect.

---

We introduced the 3-state toggle button more recently in v3: https://docusaurus.io/blog/releases/3.8#system-color-mode

Since it was not a breaking change, I decided to temporarily use a 3-state toggle so that it's less disruptive for sites upgrading to the newest minor version (using a larger layout could break site layouts with crowded navbars).

In the future, we'll likely move to a 3-choice modal like others do, so I'm not sure it's worth changing this now, and instead we should focus on shipping a modal for v4.

[Josh-Cena]

Strong -1 to changing this. One should see the color toggle as a status icon that happens to be interactable; its primary purpose should be to indicate the current state, similar to a social media "online/offline/invisible" status.

[sam-steffanus]

Strong -1 to changing this. One should see the color toggle as a status icon that happens to be interactable; its primary purpose should be to indicate the current state, similar to a social media "online/offline/invisible" status.

I believe you're conflating an icon button (the component shown in docusaurus) with a toggle switch. If docusaurus used the latter component, I would agree with you. However, most applications I've seen that use a button tend to show a moon (or the equivalent) in light mode while showing a sun (or the equivalent) in dark mode.

[Josh-Cena]

I don't think the toggle being presented as a button, switch, or select is relevant: all of them should have the icon containing the current state, because users, for 99.9% of their time on the site, aren't interested in what it's "turning into" if they aren't interacting with it; it is static and synonymous with an unclickable icon, which should present the current state.

If you look at the navbar as a whole:

Everything here is telling you the current state: that we are on version 3.8.1, that we are in the English locale, and that we are in dark mode. It would be very bizarre for two of them to show the current state, but one of them to show a "would-be state".

Thinking about it from another perspective: the current button-toggle UX is entirely a convenience feature because a two-option select is a bit overkill. Once we move to 3-way or more, then it would definitely be a select and the icon would definitely be showing the current mode. The only thing that would change in the process is the addition of a little caret symbol, but if you have to flip the icon displayed in this process, it would be too dramatic of a change.

[Vasu10134]

Hi 👋,

I’d like to work on this issue as part of Hacktoberfest 2025.
If it’s still available, could you please assign it to me? I’ll start by reviewing the current toggle logic in theme-classic and explore the appropriate update to align with the intended UX.

Thanks!

[sameersharmadev]

Hi 👋,

I’d like to work on this issue as part of Hacktoberfest 2025. If it’s still available, could you please assign it to me? I’ll start by reviewing the current toggle logic in theme-classic and explore the appropriate update to align with the intended UX.

Thanks!

Did you even read the discussion?

[AadityaBansal01]

Hi, I’d like to contribute to this issue. Could you please assign it to me?