Docusaurus: [v2] Allow Custom Dark Mode Toggle Emoji

[adrianmcli]

🚀 Feature

https://github.com/facebook/docusaurus/pull/1529 added emojis for the dark mode toggle that uses 🌞 (Sun with Face) and 🌜 (Last Quarter Moon Face).

While this is a nice touch, the choice of these emojis can look a bit un-professional when there are many other choices that are more neutral and less whimsical.

In my project, I have used this piece of CSS to hack around this and replace those emojis with the ☀️ (sun) and 🌙 (crescent-moon) emojis:

.react-toggle-track-check>span::before {
  content: '\1F319';
}
.react-toggle-track-x>span::before {
  content: '\2600';
  color: #ffd557;
}

There are many other options (like an on/off lightbulb) that users may want, so why not make this configurable?

For reference, this is where the emojis are hardcoded in Docusaurus: https://github.com/facebook/docusaurus/blob/5ccd24cc1f07efbd4e7c3fe68937e357c0e44855/packages/docusaurus-theme-classic/src/theme/Toggle/styles.module.css#L19-L24

And this is where they are set into the component: https://github.com/facebook/docusaurus/blob/5ccd24cc1f07efbd4e7c3fe68937e357c0e44855/packages/docusaurus-theme-classic/src/theme/Toggle/index.tsx#L16-L17

[slorber]

Hi,

I'm not against that idea, and like your alternate emojis too

What do you think should be the API?

Should we only allow ascii-based emojis, or enable user to provide more easily custom components like SVG components?

In any case it's possible to swizzle the toggle and customize it anyway

Do you want to submit a PR?

[adrianmcli]

If people can swizzle the component, I guess maybe we don't need this to be settable?

To be quite honest, I just really didn't like the default emojis (with the face).

I'd be happy if we could merge a PR to replace the default emojis with more sensible ones (like the ones I have).

[slorber]

As people are used to current icons and didn't complain much about those, not sure we want to replace those.

What about just providing ascii chars configuration options, so that you could easily replace those icons with the ones you like more?

Do you want to submit a PR for this?
I can assign this task to someone otherwise.

[adrianmcli]

Sure, I can try a PR this weekend.

[Drewbi]

https://github.com/facebook/docusaurus/blob/5ccd24cc1f07efbd4e7c3fe68937e357c0e44855/packages/docusaurus-theme-classic/src/theme/Toggle/styles.module.css#L19-L24

Is there a reason the emojis are added in css instead of being passed in by the themeConfig/default value in the index.tsx file?

The API could be something like:

themeConfig: {
    darkModeToggle: {
        disableIcons: false,
        darkIcon: '\1F31C' or '🌜',
        lightIcon: '\1F31E' or '🌞'
    }
}

I'm interested in working on this if you weren't planning to @adrianmcli

[adrianmcli]

@Drewbi sure, go ahead. But keep in mind that my particular use-case also requires letting users control the fill property since the sun emoji is black by default. Not sure how we want to handle this.

EDIT: I meant to say the color property.

[slorber]

I'm not against darkIconFill, lightIconFill.

Are other css attributes potentially useful to customize?
If there are we might as well directly allow passing a darkIconStyle and lightIconStyle

[adrianmcli]

I think it's a good idea to pass in darkIconStyle and lightIconStyle as I eventually made extra customizations to align the icons properly:

.react-toggle-track-check>span::before {
  content: '\1F319';
  margin-top: 1px;
  margin-left: 2px;
}
.react-toggle-track-x>span::before {
  content: '\2600';
  color: #ffd557;
  margin-left: 1px;
}

[slorber]

That's what I had in mind :p

[Drewbi]

@adrianmcli I wasn't able to check your color: #ffd557 use case as the emoji already shows up colored for me but hopefully if it worked for you in css it should work in this PR #3127

[Drewbi]

Feature has been released so we can close this :)

[adrianmcli]

Thanks everyone!

[adrianmcli]

@Drewbi I think we should also add documentation for this because I don't see it anywhere in the PR or on the site. Perhaps this page is suitable: https://v2.docusaurus.io/docs/theme-classic/#color-mode---dark-mode

[Drewbi]

@adrianmcli That is a good spot to put it, I must have missed seeing this when I was adding documentation. I added a brief example in the API page but I'll add some more here today. Thanks

[adrianmcli]

@Drewbi thank you for your hard work!