Table of Contents

How to create your own theme ?

Themes allow you to customize the colors and layout of the different components used by your application. By default the application will use a standard Neos theme.

Tip

For programmatic access to themes, use the strongly-typed Themes class instead of hard-coded strings. See Typed IDs for UI Elements for more information.

If you want to create your own theme, you can do so by adding a new theme in the module of your choice. You can either start from a standard theme or start from scratch.

In Neos Studio, the theme editor shows a tree on the left with four sections, described below: the general properties, the breakpoints, the colors and the components.

General properties

Property Description
Name, Description Identify the theme. The name is the one used to apply the theme (see below). It cannot be the name of a standard theme.
Enabled Whether the theme is generated. A disabled theme cannot be applied.
Base theme The standard theme the theme inherits from, if any. See Base theme.
Color scheme (light or dark) Tells the framework whether the theme is light or dark. See Color scheme.
Font The font used by the application. See Font.
Animated buttons Whether the buttons are animated when they are clicked. This is the default value of the animated attribute of the button component.
Reversed button order in the buttons-layout component See Reversed button order.
Module The module the theme belongs to.
Accessibility Public or Internal, with the same meaning as for any other metadata element: an internal theme can only be used by its own module.

Base theme

A theme can inherit from one of the standard themes: NeosV1, NeosV2, NeosV3 and NeosV3Dark. In that case, every value the theme does not define is taken from the base theme: the general properties, the breakpoints, the predefined colors and the component attributes. When the theme is opened in Neos Studio, the inherited values are displayed so that they can be overridden, and when it is saved, only the values that differ from the base theme are kept in the theme metadata.

The base theme is chosen when the theme is created. It can then be replaced by another standard theme with the Change base theme action, once the pending changes of the theme have been saved. The colors and component attributes inherited from the previous base theme are then replaced by those of the new one, while the overridden values are kept.

A theme without a base theme has to define everything itself: its own list of colors and a color for every component attribute. Such a theme cannot be given a base theme afterwards.

Color scheme

The color scheme is used to specify to the framework that the theme is light or dark

  • Light Theme: Uses lighter colors for backgrounds and darker colors for text and UI elements, providing a bright and clean appearance
  • Dark Theme: Uses darker colors for backgrounds and lighter colors for text and UI elements, reducing eye strain in low-light environments

This information is used by the framework to adapt the images. You can indeed define a dark version for an image. If the dark version is not defined, the image will not be differentiated between the light and dark themes. You can define this dark version :

  • by using the dedicated column in the images list
  • by adding a suffix .dark to the image name. For example, if you have an image named Customer.svg, you can add a dark version named Customer.dark.svg
Note

It is possible to get the color scheme in the client code by using the ThemeManager.GetCurrentTheme().ColorScheme property.

Font

You can choose the font of the application among Golos Text, Montserrat and Roboto. A theme based on a standard theme uses the font of its base theme by default: Golos Text for NeosV3 and NeosV3Dark, Montserrat for NeosV2 and Roboto for NeosV1.

Reversed button order in the buttons-layout component

The button order in the buttons-layout component can be reversed through a theme option. See buttons-layout documentation for more information.

Breakpoints

The theme defines the five responsive breakpoints of the application, as minimum widths of the viewport. They drive the device attribute of the grid layout and the @Viewport properties described in the viewport article.

Breakpoint Default minimum width
Small 40rem (640px)
Medium 48rem (768px)
Large 64rem (1024px)
Extra large 80rem (1280px)
Extra extra large 96rem (1536px)

Colors

The colors section lists the predefined colors of the theme: their name and their value. A theme based on a standard theme starts with the colors of its base theme, whose values can be changed. You can also add your own colors, named as you wish: a color named like a standard color sets the value of that color. In a theme based on a standard theme, the Standard color box marks the standard colors and the colors of the base theme, which cannot be renamed or deleted. A theme without a base theme starts with the names of the standard colors, without any value: fill them, rename them or delete them as needed.

For each color, the use count column shows how many component attributes use it and opens the list of these attributes, grouped by component.

For a better consistency, it is recommended to create predefined colors that can be reused across multiple components.

You can use this website to create a color palette to use in your theme.

Components

The components section lists every themable component of the framework. For each component, the customizable attributes are grouped in two tabs:

  • Colors: for each attribute, you can either choose one of the predefined colors of the theme or choose Customised to pick a specific color with a color picker. In a theme based on a standard theme, the 🔷 marker shows the attributes whose color differs from the base theme, and clearing the value restores the color of the base theme.
  • Layout: the non color attributes, such as border radiuses, margins, sizes or font sizes, entered as CSS values (for example 0.25rem).

A preview of the selected component, rendered with the theme being edited, is displayed next to the attributes and is refreshed when a value changes, before the theme is even saved. It shows the component in its different variants and states (selected, disabled, read-only, error, warning...) so that the effect of each attribute can be checked. Hover and focus colors are visible by moving the mouse over the preview or giving it the focus.

Colors of the framework components

Every color used by a framework component is a component attribute of the theme: no component reads a predefined color by its name. A theme created from scratch is therefore free to define its own list of colors, without having to keep any of the predefined color names, as long as every component attribute is assigned one of its colors.

Standard colors

The standard colors are the colors that every standard theme has, such as Primary500 or Neutral100, used in templates by their kebab-case name (primary-500) and in UI code through StandardColorNames (see UI constants). When a version of Neos adds a standard color with the name of one of your colors, your color sets its value: the changelog of each version lists the standard colors it adds.

Deprecated colors

A standard color is never removed at once: it is first deprecated, and keeps working as an alias of the color that replaces it until a later major version of Neos removes it.

Checks

neos generate reports these warnings, and the template editor of Neos Studio also shows the ones of the templates:

  • M0109: a template, a component attribute or a style class with a Neos target uses a color that an enabled theme of the cluster does not have. Define the color in every theme, use a color that they all have, or uncheck the Enabled property of a theme that the application does not use. A theme that overrides a style class in its own Neos target is checked against the colors of its override.
  • M0108: a template, a component attribute, a style class with a Neos target or a theme uses a deprecated standard color. Use the color given by the message.

How to apply your theme ?

Theme can be applied on the server side by using the ITenantResolvedInterceptor interface or on the client side.

Tenant resolved interceptor

To apply a theme, you need to create an interceptor for the resolution of the tenant and enrich the result of the previous interceptor.

Here is an example showing how to apply a custom theme :

public class TenantResolvedInterceptor : ITenantResolvedInterceptor
{
    public async Task<OnTenantResolvedResult> OnTenantResolvedAsync(NeosTenantInfo? tenant, OnTenantResolvedResult previousTenantResolvedResult)
    {
        return previousTenantResolvedResult.WithTheme("MyTheme");
    }
}

Client side

You can also apply a theme on the client side by using the ThemeManager class.

Here is an example showing how to apply a custom theme on the Initialized event of the home page UI:

_ = ThemeManager.SetThemeAsync("MyDarkTheme");
Note

It is possible to get the current theme in the client code by using the ThemeManager.GetCurrentTheme() method.