Fluentui: Update documentation on how to apply a custom Theme.

[amrock-my]

Describe the feature that you would like added

I created a React application, utilizing the Microsoft Fluent UI React library. Following the guidance from the documentation (https://developer.microsoft.com/en-us/fluentui#/controls/web/themes) I used the loadTheme() function. While this did style the components, it did not seem to apply the theme entirely on my application (body background was still white, font foreground was still black).

The styling documentation simply points to the Fluent UI Theme Designer, which helped me identify the problem. When I exported the custom theme to CodePen I noticed that the pen included the component <Fabric applyThemeToBody>. When I wrapped my <App /> component with this, everything worked fine. I'm not sure why the documentation does not mention this, but it took me two days to figure this out. The documentation points to the tool, and the tool makes it seem as if the loadTheme() function will modify the background/foreground colors automatically. Nowhere in the documentation does it talk about <Fabric applyThemeToBody>. Is this deprecated and I shouldn't use this, or is this the correct way and the documentation should be updated to reflect this?

Also, why does the CodePen use Customization.applySettings({ theme: theme }); instead of loadTheme() (they both seem to do the same thing)? Is this deprecated? Does the documentation need to be updated? Does the Fluent UI Theme Designer need to be updated to utilize loadTheme() instead to match the documentation?

What component or utility would this be added to

N/A

Have you discussed this feature with our team, and if so, who

No.

Additional context/screenshots

With <Fabric applyThemeToBody>:

Without <Fabric applyThemeToBody>:

[paulgildea]

@amrock-my This is a great and detailed feature request! Thank you!

Yes this is great feedback and we should really make this more straight forward especially since there has been more focus on "dark modes" in products.

@aneeshack4 - Is this something you can look into?

@JustSlone - if @aneeshack4 can't take a look at this - can we get this on the July schedule?

[rhummelmose]

Why is nobody answering this? Is there no way of using themes without calling deprecated methods?

[JonSilver]

@amrock-my we would very much like an answer to all these questions as well, and documentation for the best-practice current/future theming methodology. I'm not sure why nobody's answering after all this time.

[xugao]

@amrock-my @rhummelmose @JonSilver - sorry for the delayed response as well as the unclear documentation!!

You are correct on using loadTheme. Customization.applySettings({ theme: theme }); is incorrect, which I will fix. Here is a correct pen to demo.

<Fabric applyThemeToBody>
Is this deprecated and I shouldn't use this, or is this the correct way and the documentation should be updated to reflect this?

As of now (@fluentui/react@7), this is the correct to use. applyThemeToBody will apply body theme (e.g. theme.sematicColors.bodyBackground) to document body. One caveat here is we are currently prepping for next major release (#12770) and in this release we want to replace Fabric with a new component called ThemeProvider. You can read more details here. Depends on the state of your app, you might want to pick up ThemeProvider directly and avoid using Customizer or loadTheme or Fabric. Please do note that this is still currently under development and it won't be official until we release @fluentui/react@8-beta.*. (estimated to be available in 2 weeks)

Please let me know if you have more questions!

[JonSilver]

Thanks @xugao. It's good to know improvements are in the pipeline. But these breaking changes and dead ends can be frustrating for folks, especially when the documentation doesn't keep up or when there are seemingly multiple sources of truth without it being clear which one is authoritative.

@amrock-my @rhummelmose I've published a Fluent UI Create React App Demo App that illustrates how we've created our own Context API-based theme provider for Fluent UI. It also fixes up the theming of global anchor tags (links) to match the selected theme. Of course it's based upon the currently available ways of doing things, but I'll try to keep it updated as an evolving live item of documentation for Fluent UI. It's not "pure", in that it demonstrates a whole bunch of other useful stuff too, but hopefully it should be clear what does what.

Kind regards,
Jon Silver
R&D Director
JFDI Consulting Ltd
Microsoft Gold Partner
Preferred Partner, Microsoft 365 Business Apps

[xugao]

@JonSilver - Yes, our apologies! I will be working on cleaning up / improving the documentations around theming. I will update this issue once documentation is updated.

Also, I just glanced at your theming code in the demo app - I would replace Customization.applySettings({ theme }) with loadTheme(theme).

[JonSilver]

Thanks @xugao I've made that modification, tested & checked it in.

[mturoci]

The documentation states that loadTheme must be called before app startup. Is there any way to change theme after the app startup? E.g. toggling dark / light mode.

cc @xugao

[JonSilver]

Is there any way to change theme after the app startup? E.g. toggling dark / light mode.

Hi @mturoci if it helps, there's a demo of how to do this in our demo app I referenced above (not connected with the dev team here). Apparently the dev team is working on a Theme Context Provider just like ours, but feel free to dig in and get the job done right now,

[xugao]

@mturoci @JonSilver - @fluentui/react@v8-beta is available now to consume. As part of it, we introduced ThemeProvider which is described here. I highly recommend you to try it out and please let me know if you have further questions/concerns!

[bonafideyan]

when the backgound color has been merged into classname with mergeStyleSets method, what should I do after change theme? css variable help?