So I think the documentation I should be reading is https://material-ui.com/customization/theming/ however that isn't obvious when you end up on the styling section.

Apparently I shouldn't have been reading the documentation on theming, instead I should have been looking at the documentation theming.

The styling section is a natural place to end up immediately after reading the documentation on components as its the very next section down. It also tends to turn up in Google searches since I'm thinking styling (from css) and thus that is my search terms. After reading basic styling this naturally leads to the advanced styling page, where one immediately spots the heading titled "Theming".

While there is a small notice box above the first example, it doesn't actually make much sense until you understand theming.

Finally, on the first page of the theming overview, one of the first links for "Theme provider" is to the API section, taking directly back to styles section (just below the advanced section). So after reading the API section one is almost certainly going to then check the basic styling and advanced styling guides.

@chilversc Thanks for the feedback, we had the same one in #20136 that we tried to fixed with a better warning message.

A couple of options:

1. Update all the demos to use createMuiTheme(). Do we have more cases like this page to handle? https://material-ui.com/styles/advanced/.
2. Warn if the theme has missing keys, at the component level, right now, it's simply thrown. Hopefully, it's simple to figure what's wrong: theme.shadows.forEach(function (shadow, index) { => theme.shadows is undefined.
3. We do nothing
4. Else?

I think the issues here is to look at the flow (i.e. the order of the sections), and avoid having duplicate or similar titles (i.e. two different pages both called theming).

The other thing that would really help is some sort of glossary or overview, because when it comes to theming and styles there's a lot of overlap and its hard to know what any of it means until you realise what the purpose of the different sections are. This is then compounded by the different options such as withStyle, withTheme, useStyle, etc.

I think the main issue here is there's actually two separate discussions happening with in the same documentation set. The main documentation is all about Material UI, thus when reading the style section one is approaching it Material UI as the context. However, the advanced styles section is really discussing two things, the Material Styles library (without UI), and advanced usages of themes/styles within Material UI.

If these sections were broken up it would be a lot simpler to describe (at the cost of some duplication). As in the Material UI documentation all the examples can include createMuiTheme and approach it as someone using this within a Material UI app.

There could be a separate set of documentation for Material Styles that can then focus on how the underlying library works, and how it could be used independently of Material UI. I would then consider having the Style documentation under a completely separate set of pages with links between the projects.

There could be a separate set of documentation for Material Styles that can then focus on how the underlying library works, and how it could be used independently of Material UI. I would then consider having the Style documentation under a completely separate set of pages with links between the projects.

@chilversc Interesting, we have been wondering about going in this direction in the past, mainly influenced by how jQuery used to differentiate its different projects in the UI:

I think that we could consider doing something similar with the "unstyled" effort. It's going to be an interesting discussion to have once we make progress with the actual implementation. How do we market it? How do we document it? Sorry, I'm going off track.

So, back to v5, we aim to move Material-UI styles to third-parties: https://cssinjs.org/, https://styled-components.com/, and http://emotion.sh/.

In the mean time, I think that warning needs to be a bit more prominent. Perhaps instead of an alert box it should be part of an introduction / read first section.

I was thinking of something like this:

These examples in the advanced section refer to the @material-ui/styles library. The styles library can be used independently from the @material-ui/core library, and supports the core library by providing styling and theming support.

IMPORTANT: The examples shown in this section will not work with the standard @material-ui/core classes. The examples show how you can use styles and themes within your own application independently from @material-ui/core.

To use these functions with Material UI components you will need to use the createMuiTheme function from @material-ui/core/styles (not to be confused with @material-ui/styles).

See the theming section section for examples on how to use themes and styles with Material UI components.

Though I do find it odd in a section that is supposed to be all about the @material-ui/styles, all of the examples use the re-exported functions from @material-ui/core/styles? See the first example from https://material-ui.com/styles/basics/.

import React from 'react';
import { makeStyles } from '@material-ui/core/styles';
import Button from '@material-ui/core/Button';

This doesn't help draw a distinction between what is provided by styles, and what is provided by core.

Unfortunately, a lot of those examples are useful for both the styles library (stand-alone) and the core library, such as using hooks and higher order components. I can't see a way to avoid duplication of the examples while maintaining clear separation between styles and core.

Just thought, might even be useful to include an example of what happens when you do get the wrong method in the section on "@material-ui/core/styles vs @material-ui/styles" mentioning some of the most common error messages you will get to aid with searching for the error.

When using @material-ui/core a common mistake is to use the styles library, or forget to use createMuiTheme.

In such a case you will likely receive errors such as:

• theme.shadows is undefined
• theme.typography is undefined

Check the following:

• You are using createMuiTheme to create your initial theme
• Nested themes overriding an outer theme must copy the outer theme's properties outer => { ...outer, /* overrides */ } (unless they create a new theme using createMuiTheme).
• You are using @material-ui/core/styles (it is common to mistake this with @material-ui/styles).

See the theming section for examples.

I think that we can go with the proposal of @eps1lon, adding createMuiTheme in the example sounds like the simplest solution.