- what are the different properties of the theme object
- how to properly access the theme object in the code
The theme object defines different visual aspects of our website, for example the default set of colors, typography, breakpoints, and more.
Apart from being used in the code by different page elements, the theme object is also integrated with different editors that are available in the Page Builder’s application, like page or block editor.
For example, colors or different typography options defined in the theme object are automatically picked up by these editors, enabling users to select them while building content and ensuring everything stays visually consistent.
By default, the theme object is exported from the
apps/theme/theme.ts file, and it looks like the following:
In the following text, we cover all the different properties of which the theme object consists of.
breakpoints object, the theme object defines four available breakpoints:
- mobile (landscape orientation)
- mobile (portrait orientation)
Note that the property names of these breakpoints (
mobile-portrait) should not be changed. But, the assigned media queries can be adjusted and new ones can be introduced, if need be.
styles.colors object, the theme object defines theme colors, where property names represent the IDs of colors and values respective color codes.
The IDs of colors don’t follow any naming convention. Upon introducing new colors, IDs like
myCustomColor will work as well.
styles.typography object, the theme object defines theme typography. Unlike with breakpoints and colors, property names here represent the typography categories, and values array of different typography variants. For example, in the following code snippet, we can see six different heading variants being defined:
Every typography variant consists of the following properties:
|A unique ID of the typography variant. Like with colors, typography IDs don’t follow any naming convention. Upon introducing new typography, IDs like |
|A human-readable name of the typography variant. Will be shown in different Page Builder editors like page or block editor.|
|A HTML tag that will be used to render the typography variant.|
|A CSS object that defines the visual appearance of the typography variant.|
Note that, when accessing the theme object and different typography variants, to make it easier, we can leverage the
stylesById getter function. More on this below, in the Accessing the Theme
styles.elements object enables defining and overriding styles for new and existing page elements. Like with colors and typography, property names represent the IDs of page elements, and values respective CSS rules that define them visually.
To learn more about custom page elements, check out the existing Create a Custom Page Element article.
While styling page layouts or custom page elements, the theme object can be accessed in order to use the styling rules defined in it. To access the theme object, we rely on Emotion’s suggested approach, which is through the React context.
The easiest way to access the theme object is via styled components, like in the following example:
As we can see, the
theme object is available via the
props argument of the styled component’s template literal function. This means that we can access any of the theme object’s properties, like
Note that the theme object should not be accessed by directly importing the
apps/theme/theme.ts file. This can
lead to issues in multi-theme projects, where the theme object is not the same for all themes.
When accessing typography variants, we can leverage the special
stylesById getter function, like in the following example:
As we can see, the
stylesById getter function accepts a typography variant ID as an argument, and returns a CSS object that defines the visual appearance of the typography variant. This way, we can easily access different typography variants, without having to manually traverse the
If needed, theme object can also be accessed when creating custom page elements, via the
useRenderer React hook. For example:
Most often, styles for custom page elements are introduced via one or more standalone Emotion styled components.
The theme object allows users to define responsive styles for all of the above mentioned properties. Consider the following example:
In this example, we’ve defined responsive styles for the
heading1 typography variant. This means its styles will be different depending on the device’s screen size. For
desktop, the font size will be
tablet it will be
mobile-landscape it will be
24px, and for
mobile-portrait it will be
Note the use of breakpoint names (like
tablet, etc.) instead of breakpoint values (like
@media (max-width: 4000px)). This is because the theme object automatically converts breakpoint names to breakpoint values, based on the
breakpoints constant defined at the top of the
apps/theme/theme.ts file (and assigned via the
breakpoints property in the exported theme object).
When Defining Custom Theme, Should I Create a Copy of the Theme or Can I Just Override the Values I Need?
In general, it depends on your needs and personal preference. There’s nothing wrong with simply overriding the values you need.