Customize a theme

Overview

App Builder allows various theme properties to be overridden, and we are extending support for overriding further properties regularly. Overriding of theme properties works by passing the URL parameter called g as described in the section URL parameters of Embed Apps in external websites. The value of g is a relative or absolute URL to a JSON file defining the theme properties to be overridden. An example:

App using the default theme
App using some theme overrides (relative URL)
App using some theme overrides (absolute URL)
Theme JSON file

When self-hosting your theme JSON file, you need to use an absolute URL for the file.

Capabilities

Besides influencing the app's appearance, the theme can also influence its behavior. The theme JSON file supports the following top-level properties:

Property	Description
`version`	Mandatory. Currently, this always needs to be set to `"1.0"`.
`sessions`	Optional array of session definitions. This allows you to define the sessions to create. Currently, this supports a single session only. When specifying a session, you can avoid specifying `slug` or `ticket` and `modelViewUrl` as separate URL parameters. Examples: Define a session by a `slug` (App, Theme JSON) Define a session by a `ticket` and `modelViewUrl` (App, Theme JSON)
`themeOverrides`	Optional. This allows you to override classical UI theme properties (the appearance). We've included details about this below.
`appBuilderOverride`	Optional. This allows you to override the JSON content of the `AppBuilder` data output of your Grasshopper model. Useful for local testing. Example: Model without `AppBuilder` data override (App, Theme JSON) Model with `AppBuilder` data override (App, Theme JSON)

Theme overrides

This section explains the properties of themeOverrides and how to use them.

General considerations

App Builder is based on the Mantine React components library. Mantine comes with out-of-the-box theme support, which you can read about here. You can override all of the properties supported by Mantine’s theme object by setting these properties in the themeOverrides property. Example:

CODE

{
  "version": "1.0",
  "themeOverrides": {
    "primaryColor": "pink",
    "defaultRadius": "0"
  }
}

An example app using this theme: App, Theme JSON.

These properties override the default theme defined by App Builder. Read more about it in the following.

Many theme properties can be specified responsively, by defining their values dependent on the device width. You can find the default breakpoint values here.

Default theme used by App Builder

You can find the default theme used by App Builder in the GitHub repository of the App Builder SDK: useCustomTheme.ts

The default theme of App Builder overrides almost none of the top-level properties of Mantine’s default theme. However, it overrides the default properties of several components:

Overriding component properties

The components property of Mantine’s theme allows the overriding of default values for all of Mantine’s components. When implementing the React components of App Builder, we use the same mechanism to allow the overriding of their properties. You can see this when inspecting the default theme used by App Builder. The table below shows some examples of what can be achieved by this:

Component
AppBuilderAppShellTemplatePage	The default page template used by App Builder. This template is built on top of the AppShell component. This component supports overriding a few properties that can be used to influence the width and height of the containers and the page's responsive behavior. The main viewport area, the bottom container, and the right container use a grid layout. Examples: Default property values (App, Theme JSON). This is a good example from which to start adapting your theme. Example 01 (App, Theme JSON). This example uses a varying number of columns and rows depending on screen width. For smaller screen widths, the bottom container takes the full width. These examples also contain the top-level properties `sessions` and `appBuilderOverride`. You can remove them and instead specify your model's `slug` as a URL parameter.
ViewportIcons ViewportOverlayWrapper	These components allow you to define where to place the viewport icons, which of the icons to show, etc. Example: Bigger icons displayed on the bottom left of the viewport (App, Theme JSON)
AppBuilderContainerWrapper	This component wraps all containers (left, right, top, bottom) and can be used to override theme properties for individual containers. An example of this can be found in the default theme.
AppBuilderGridTemplatePage	An alternative page template that uses a pure grid layout. Theme overrides can be used to change the number of columns and rows, and the number of columns or rows used for the containers. Override the default properties of AppBuilderTemplateSelector to select this page template.
AppBuilderImage	The component wrapping all images.
AppBuilderHorizontalContainer	The common wrapper for all horizontal containers.
AppBuilderTemplateSelector	Allows to specify which page template should be used.
AppBuilderTextWidgetComponent	The text widget component.
TooltipWrapper	Defines how to render tooltips.