UI Framework Styling

• 4 minutes to read

UI Themes

The UI Framework uses a theme engine for styling. To change the styles of UI elements, this engine uses CSS custom properties (variables).

The distribution package contains a default UI theme in the themes folder (ui-framework/<vers>/themes). To find all the defined variables, open a theme file, for example, au-default-theme.html and scroll to the following elements:

<custom-style>
    <style>
        html {
            --theme-primary-color: #0090ff;
            ...

You can activate themes in the editor.json file as follows:

"imports": [
  {
    "src": "themes/au-default-theme.html",
    "check": "true"
  },
  ...
]

To create a custom theme, you can copy, rename, and edit the au-default-theme.html file as needed. If you split a theme into different files, then you must import those files as described above.

Icons

At the beginning of the default theme, there is an iron-iconset-svg element with predefined SVG icons for steps, groups, etc. Each icon is enclosed in the tag <g> and has a unique ID. The size of icons is 32x32 px.

<iron-iconset-svg name="custom-icons" size="32">
    <svg>
        <defs>
            <g id="preloader" viewBox="0 0 32 32" ...
            <g id="front" viewBox="0 0 32 32" ...

Here, you can define new icons by using both vector path and raster image elements.

To add a raster image as an icon, for example in the PNG format, convert it to Base64 first. You can use such online tools as https://www.base64-image.de for the conversion. After that, paste the resulting string into the xlink:href attribute of the image element.

<g id="pngIcon" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
  <image x="0" y="0" width="32" height="32"
      xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUh ...
</g>

Colors

The custom-style element contains the html object with variables defining the theme colors.

<custom-style>
  <style>
      html {
          --theme-primary-color: #30c2ff;
          --theme-primary-color-hover-button: rgba(48, 194, 255, 0.12);
          --theme-background-color: #ffffff;
          --theme-preloader-size: 50px;
          ...

For example, you may want to change the primary color --theme-primary-color, which will be applied to all icons, buttons, and other control elements.

As an alternative to editing variables in the HTML file, you can redefine them directly in your config. To do this, you can use the style object in any widget or directly in the root of the config as follows:

{
  "style": {
      "--theme-primary-color": "#30c2ff"
  }
}

Vertical mobile layout

When you enable the vertical mobile layout, you can configure the appearance of panels: the main panel height, margins, and panel order.

You can define them in the html object of custom-style in the theme HTML file. Let's learn how you can do this and take a look at the default settings.

<custom-style>
  <style>
      html {
        /** Vertical size of the main panel, in percent of viewport height. */
        --theme-vertical-mobile-main-height: 90vh;
        /** Margin between panels, in pixels. */
        --theme-vertical-mobile-panel-margin: 20px;

        /** Order of panels. */
        --theme-vertical-mobile-top-order: 10;
        --theme-vertical-mobile-left-order: 30;
        --theme-vertical-mobile-main-order: 20;
        --theme-vertical-mobile-right-order: 40;
        --theme-vertical-mobile-bottom-order: 50;
        ...
      }
  </style>
</custom-style>

The lower the order, the higher the panel will be in the window.

As an alternative to editing variables in the HTML file, you can redefine them in the root object style of your config. You can do this as follows:

{
  "style": {
    "--theme-vertical-mobile-main-height": "70vh",
    "--theme-vertical-mobile-panel-margin": "10px"
  }
}

Note

The vertical mobile settings only apply to the application running on mobile devices and don't affect the application when working in desktop browsers.

Custom Preloader

You can change both the color and the image of the preloader in the UI Framework.

To change the color, set a new value to the --theme-primary-color variable.

To change the icon, replace the content of the element <g id="preloader" ... >.

<g id="preloader" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg"> 
    ...
</g>

To specify the icon size, define the viewBox attribute depending on the size of your SVG image. In the previous example, we defined the standard size of 32x32 px. When you use a custom icon, you may need to change the size of the circular progress ring in the --theme-preloader-size variable.

Note

The design-editor widget uses a different preloader. To customize it, refer to the corresponding topic.

Icons and Headers of the Panels

You can use the drawer object to specify icons and headers of the UI Framework panels. To enable an icon, add the icon property and refer to the required SVG image in the theme file through <iconsetName>:<iconId>.

In the following example, we set the front icon and the Size header to options in the toolPanel.

{
  ...
  "steps": [
      {
          "name": "1. Card",
          "title": "Step 1. Card Options",
          "icon": "custom-icons:front",
          "description": "Personalize your card here.",
          "mainPanel": {
              "name": "editor"
          },
          "toolPanel": {
              "name": "options",
              "drawer": {
                  "icon": "custom-icons:front",
                  "text": "Size"
              }
          }
      },
    ...
  ]
}

Changing styles via config

It is not always convenient to wait for a release with a style update. Sometimes you may want to redefine styles in the config. To do this, you can use a "css" node in each widget and directly in the root of the config:

{
   "css": ".myclass { color: red;} .mysecondclass { margin: 0 !important;}"

}