What You’ll Learn
  • what are the different properties of the theme object
  • how to properly access the theme object in the code

Overview
anchor

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.

Theme Colors Available In The Color PickerTheme Colors Available In The Color Picker
(click to enlarge)

By default, the theme object is exported from the extensions/theme/src/theme.tsexternal link file, and it looks like the following:

extensions/theme/src/theme.ts

In the following text, we cover all the different properties of which the theme object consists of.

Properties
anchor

Breakpoints
anchor

Via the breakpointsexternal link object, the theme object defines four available breakpoints:

  1. desktop
  2. tablet
  3. mobile (landscape orientation)
  4. mobile (portrait orientation)

Note that the property names of these breakpoints (desktop, tablet, mobile-landscape, mobile-portrait) should not be changed. But, the assigned media queries can be adjusted and new ones can be introduced, if need be.

Colors
anchor

Via the styles.colorsexternal link 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 primaryColor or myCustomColor will work as well.

Note that color IDs are used as references in pages created via the Page Builder's page editor. Meaning, changing them will cause existing pages (that are already relying on previous IDs) to break and not resolve the selected colors correctly.

Typography
anchor

Via the styles.typographyexternal link 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:

extensions/theme/src/theme.ts

Every typography variant consists of the following properties:

PropertyDescription
idA unique ID of the typography variant. Like with colors, typography IDs don’t follow any naming convention. Upon introducing new typography, IDs like primaryTypography or myCustomTypography will work as well.
nameA human-readable name of the typography variant. Will be shown in different Page Builder editors like page or block editor.
tagA HTML tag that will be used to render the typography variant.
stylesA CSS object that defines the visual appearance of the typography variant.
Note that typography variant IDs are used as references in pages created via the Page Builder's page editor. Meaning, changing them will cause existing pages (that are already relying on previous IDs) to break and not resolve the selected typography correctly.

Note that, when accessing the theme object and different typography variants, to make it easier, we can leverage the special stylesById getter function. More on this below, in the Accessing the Theme Object section.

Page Elements
anchor

Respectively, the styles.elementsexternal link 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.

By default, the property contains styles for default documentexternal link and buttonexternal link page elements, but note that styles for custom ones can be added here as well.

Although page elements can have their styles defined within one or more respective React components, in multi-theme projects, having all or just part of the element's styles defined here can make it easier to have different styles for different themes.

To learn more about custom page elements, check out the existing Create a Custom Page Element article.

Accessing the Theme Object
anchor

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 componentsexternal link, 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 styles.colors, styles.typography or styles.elements.

Note that the theme object should not be accessed by directly importing the extensions/theme/src/theme.tsexternal link file. This can lead to issues in multi-theme projects, where the theme object is not the same for all themes.

Multiple examples of accessing the theme object can be found in the Static page page layout code that’s included by default in all new projects. The code is located in the extensions/theme/src/layouts/pagesexternal link code folder.

More information on page layouts can be found in the following Page Layouts article.

Accessing Typography Variants
anchor

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 styles.typography object.

Custom Page Elements
anchor

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 componentsexternal link.

Responsive Styles
anchor

The theme object allows users to define responsive styles for all of the above mentioned properties. Consider the following example:

extensions/theme/src/theme.ts

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 48px, for tablet it will be 36px, for mobile-landscape it will be 24px, and for mobile-portrait it will be 20px.

Note the use of breakpoint names (like desktop, 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 extensions/theme/src/theme.tsexternal link file (and assigned via the breakpointsexternal link property in the exported theme object).

FAQ
anchor

When Defining Custom Theme, Should I Create a Copy of the Theme or Can I Just Override the Values I Need?
anchor

In general, it depends on your needs and personal preference. There’s nothing wrong with simply overriding the values you need.

Is Having Multiple Themes Supported Out of the Box?
anchor

Out of the box, every Webiny project starts with a single theme (the one located in the extensions/themeexternal link folder. For a multi-theme setup, please take a look at the Setup Theme Manager article.