Customize Styling

Last modified: October 8, 2026

Introduction

This page describes how developers can change the styling of apps and create re-usable styling. For progressive and web apps, theme settings are CSS variables (custom properties) and styling is written in SASS (SCSS). For native mobile apps, JavaScript is used. Even though the technologies differ, the approach for customizing styling is the same.

This page describes styling for Atlas UI 4, where the web theme settings are CSS variables. If your app still uses Atlas UI 3, see Customize Styling in the Studio Pro 10 documentation. To move your app to Atlas UI 4, see Migrating to Atlas UI 4.

Changing the App Look and Feel

Developers have several options to change an app's look and feel.

Changing the Default Theme Settings

When tailoring your app's look, a simple first step is to change the theme settings. This quickly adjusts the theme to a company's brand by changing the colors.

To customize the default theme settings for native mobile apps, you can open and edit the custom-variables file from the App Explorer (App > Styling > native > custom-variables.js).

For web apps, the theme settings are CSS variables. Atlas Core defines all of them, with their default values, in themesource/atlas_core/web/themes/_theme-default.scss. The custom-variables.scss file of your app (App > Styling > web > custom-variables.scss) lists these variables in a :root block and shows the format to follow.

To change a theme setting, the steps that you could follow are:

Create a new file in theme/web, for example theme/web/theme-settings.scss. In the new file, declare the variables with a new value inside a :root block, following the format described in custom-variables.scss:
```
:root {
    --brand-primary: #0a6cff;
    --font-size-default: 15px;
    --border-radius-default: var(--border-radius-m);
}
```
Import the new file in theme/web/main.scss by adding the following:
```
@import "theme-settings";
```

A file that is imported in main.scss is included once, so each of your theme settings is declared once in the stylesheet of your app.

You only need to declare the variables you want to change. All other variables keep the default value from Atlas Core.

The $use-css-variables: true; line in custom-variables.scss tells Atlas Core that your theme settings are CSS variables, and must stay in that file.

A small number of theme options are still SASS variables, because they control what is compiled into the stylesheet. These are not declared in a :root block:

$brand-logo, $font-family-import, $form-input-style, and $btn-bordered, which are set in custom-variables.scss
The breakpoints, such as $screen-md and $screen-lg, which are set in custom-variables.scss
The exclusion variables described in the Disabling Default Styling from Atlas Core section below

For more information on how changes can be quickly previewed, see the Preview a Styling Change section below.

Using Color Shades

For each of the colors --brand-primary, --brand-success, --brand-warning, --brand-danger, --brand-default, and --gray, Atlas Core generates a scale of ten shades. The shades are named after the color, followed by 50, 100, 200, 300, 400, 500, 600, 700, 800, or 900. For example, --brand-primary-100 is a light shade of the primary color and --brand-primary-700 is a dark shade. Shade 500 is equal to the color itself.

The shades are calculated in the browser from the base color, so you do not have to define them. When you change --brand-primary, all the shades of the primary color change with it. You can use the shades as the value of other variables or in your own styling:

:root {
    --brand-primary: #0a6cff;
    --bg-color: var(--brand-primary-50);
    --link-hover-color: var(--brand-primary-700);
}

Lighter shades are mixed with --color-base (white by default), and darker shades are mixed with --color-contrast (black by default).

Using the Styling Editor

The styling editor is based on the editor that powers Visual Studio Code and is also used for JavaScript actions. You can find the styling files (JS, SCSS) and theme settings (JSON) under App Explorer's Styling node. When you double-click a styling file, it will be opened in the styling editor:

By default, Studio Pro shows styling files on the app level and from UI resources modules, such as Atlas_Core. This can be changed in preferences (Edit > Preferences > General > Interface) or by simply right-clicking Styling in the App Explorer:

To learn more about the file and folder structure, see the File and Folder Structure section below.

Adding Custom Styling

Developers can add custom styling for apps in the theme/web or theme/native folder.

For (progressive) web apps, custom styling should be placed in theme/web and linked from (or placed in) main.scss. For native mobile apps, custom styling should be placed in theme/native and linked from (or placed in) main.js.

While custom styling can be added directly in the main.scss or main.js it is a best practice to separate styling in files and include these files in main.scss or main.js.

Within custom styling, the theme settings (colors, spacings, etc.) as configured in custom-variables.scss or custom-variables.js, can be re-used. This is also recommended to provide a consistent user experience. For web apps, use the var() function to read a theme setting, for example color: var(--brand-primary);.

Web Environment Example

In the following example a custom style is added to change any matching element's font-size upon use.

Steps:

In your previously created theme settings file (for example theme/web/theme-settings.scss, see Changing the Default Theme Settings above), add a CSS variable by adding the following code inside the :root block:
```
:root {
    --company-header-text-size: 30px;
}
```
Create a new file theme/web/company-header.scss. In the new file create a class with a selector name (.company-header) and include a CSS property that references the variable created in step 1.
```
.company-header { font-size: var(--company-header-text-size); }
```
Import the new file in theme/web/main.scss by adding the following:
```
@import "company-header";
```

This ensures the SCSS is included in CSS compilation.

Native Environment Example

In this example we will be creating a custom style which will change the font size of text upon use:

Add a JavaScript variable in theme/native/custom-variables.js with the following code:
```
export const companyHeaderTextSize = 30;
```
Create a new file theme/native/company-header.js. In the new file, the newly defined variable defined in step needs to be imported. Create a variable with an object value, containing property fontSize with the value referencing the newly defined custom-variable, then export the variable. The following code achieves this:
```
import { companyHeaderTextSize } from "./custom-variables";
export const companyHeader = { fontSize: companyHeaderTextSize };
```
Import the object defined in company-header.js and expose it in theme/native/main.js as follows:
```
import {companyHeader} from "./company-header";
module.exports = {companyHeader};
```

Adding a Theme Variant (Web Only)

Because the theme settings are CSS variables, the browser applies them while the app is running. This makes it possible to offer more than one look in the same app, for example a dark theme, without compiling a second stylesheet.

A theme variant is a set of variable overrides that only applies when a class is present on the root element of the page. To add a dark theme, do the following:

Create a new file theme/web/theme-dark.scss and override the variables that should differ from the default theme:

:root.theme-dark {
    --color-base: #1e1e1e;
    --color-contrast: #ffffff;
    --bg-color: var(--brand-primary-50);
    --bg-color-secondary: var(--brand-primary-100);
    --border-color-default: #6c757d;
}

Import the new file in theme/web/main.scss by adding the following:
```
@import "theme-dark";
```
Add the theme-dark class to the root element (<html>) of the page to switch to the variant, and remove the class to switch back. Atlas Core does not set this class. You can set it yourself, for example with a JavaScript action that is called from a button:
```
document.documentElement.classList.add("theme-dark");
```

The color shades are mixed with --color-base and --color-contrast. Therefore, when a dark theme swaps these two variables, all the shades are recalculated for a dark background.

Importing CSS (Web Only)

An app's theme is based on SASS (.scss files), but it can be the case you require CSS files from third-party libraries. This can be done by adding the third-party library file to the cssFiles property in theme/web/settings.json.

See the following fragment as an example of how additional CSS can be added to your app. Below, a third-party CSS file water.css is added and will be applied to the app. The third-party CSS file should be in theme/web:

{
	"cssFiles": ["theme.compiled.css", "water.css"]
}

Creating Re-Usable Styling

The previous section describes how developers can customize the styling of an app. Next to that it is possible to place styling inside modules, which then can be re-used in other apps. This can be used to create a theme module or a company design system.

Adding styling to a module is similar to adding styling to an app, except that styling resources are placed in the themesource folder as explained in the File and Folder Structure section below.

For classes that are generic or that should be easily discovered, a developer can consider creating design properties for this. For more information, see How to Extend Design Properties.

Creating a Theme Module

A theme module is useful for styling which can be easily re-used through modules across apps. By default, the theme settings like color, font, spacing, and more are in the theme folder, which is specific per app. However, often these settings should be re-used to create a consistent look and feel across apps.

This can be done by creating a theme module and making the custom-variables file in the theme folder point to the custom variables file in your theme module. For creating a full design system see How to Create a Company Design System.

See the examples below for more information on creating a re-usable theme module.

Marking as a UI Resources Module

Modules that contain theme styling should be marked as UI resources modules. To do so, right-click the Module {name} in the App Explorer, then click Mark as UI resources module. This will give the modules a green icon, which makes it easy to distinguish theme modules from other modules, and also influences the order in which styling will be applied from those modules:

Ordering UI Resource Modules

When a module contains styling (SCSS/CSS), be sure it is added to the compiled CSS file in the correct order relative to other files. For example, if a theme module should override styling that is defined in Atlas_Core, it is important that the theme module is added after Atlas_Core.

You can set an explicit order in the theme settings (App Settings > Theme). This contains a list of all modules that are marked as UI resource modules, and allows you to set the explicit order in which they are added to the CSS file. Note that the lower a module is ordered in the list, the higher its precedence. For example, an app that uses a company theme module could be ordered as follows:

Examples

Web

As an example, the following variables in theme/web/custom-variables.scss will be made into a re-usable theme module:

:root {
    --brand-primary: #264ae5;
    --brand-success: #16aa16;
    --brand-warning: #cd8501;
    --brand-danger: #ea3337;
    --gray: #b8babf;
}

To create a re-usable theme module, do the following:

Create a new module in Studio Pro. Right-click App {name} in the App Explorer, then click Add module…. Give it a name. For this example the module’s name is "mytheme".
In your Mendix app directory, create a new file themesource/mytheme/web/custom-variables.scss.

To open your Mendix app directory from Studio Pro, click App in the top menu-bar, then click Show App Directory in Explorer.
Copy the :root block with the variables from theme/web/custom-variables.scss and paste it in themesource/mytheme/web/custom-variables.scss. Remove the :root block from theme/web/custom-variables.scss. Leave the $use-css-variables: true; line in place.
In theme/web/custom-variables.scss add @import "../../themesource/mytheme/web/custom-variables.scss" to the top of the file, replacing "mytheme" with your module name. The theme/web/custom-variables.scss file should only contain an import statement to your "mytheme" custom variables and the $use-css-variables: true; line.

The two files should end up looking like this:

theme/web/custom-variables.scss:

@import "../../themesource/mytheme/web/custom-variables.scss";

$use-css-variables: true;

Any variables declared in a :root block in theme/web/custom-variables.scss after the import statement will override the variables in themesource/mytheme/web/custom-variables.scss.

themesource/mytheme/web/custom-variables.scss:

:root {
    --brand-primary: #264ae5;
    --brand-success: #16aa16;
    --brand-warning: #cd8501;
    --brand-danger: #ea3337;
    --gray: #b8babf;
}

You can now export the mytheme module from Studio Pro to re-use in your apps. Note that you need to add the @import … line to theme/web/custom-variables.scss for every app that imports the module. Therefore, Mendix recommends creating a company starter app containing this change.

To test the theme for all the widgets, page templates, and building blocks it can be helpful to use the Atlas Design System app as discussed in Create a Company Design System.

Native Mobile

As an example, the following variables in theme/native/custom-variables.js will be made into a re-usable theme module:

export const brand = {
    primary: "#264AE5",
    success: "#3CB33D",
    warning: "#ECA51C",
    danger: "#E33F4E",
    info: "#0086D9",
    primaryLight: "#F3F5FF",
    successLight: "#F1FCF1",
    warningLight: "#FFF9E6",
    dangerLight: "#FFEEF0",
    infoLight: "#ECF9FF"
};

Steps:

Create a new module in Studio Pro. Right-click App {name} in the App Explorer, then click Add module…. Give it a name, for this example the module’s name is "mytheme".
In your Mendix app directory, create a new file themesource/mytheme/native/custom-variables.js.

Note: To open your Mendix app directory from Studio Pro, click App in the top menu-bar, then click Show App Directory in Explorer.
Cut the export statement and variables from theme/native/custom-variables.js and paste in themesource/mytheme/native/custom-variables.js.
In theme/native/custom-variables.js add the following code to the top of the file, replacing "mytheme" with your module name:
```
export * from "../../themesource/mytheme/native/custom-variables";
```

The two files should end up looking like this:

theme/native/custom-variables.js:

export * from "../../themesource/mytheme/native/custom-variables";

themesource/mytheme/native/custom-variables.js:

export const brand = {
    primary: "#264AE5",
    success: "#3CB33D",
    warning: "#ECA51C",
    danger: "#E33F4E",
    info: "#0086D9",
    primaryLight: "#0086D9",
    successLight: "#F1FCF1",
    warningLight: "#FFF9E6",
    dangerLight: "#FFEEF0",
    infoLight: "#ECF9FF"
};

If you get errors, double check if the imports point to valid files.

When this approach is used, Mendix recommends creating a company starter app. Out-of-the-box this app will contain the theme module, and already contains this change in the theme folder that points to the module.

Previewing a Styling Change

Depending on the type of app you are building, the preview of styling or a theme change is different.

Web apps

Mendix monitors the file system in the theme and themesource folder for changes in the .scss files. When a change is detected, the .scss files are compiled to CSS and the app is automatically reloaded (if it is running), so no additional tooling is needed. For more information on how the SCSS is compiled see the Styling Output section below.

Native Mobile Apps

Mendix monitors the file system in the theme and themesource folders for changes in the .js files. When loading a native mobile app in the Make it Native app there you will see the Enable developer mode option. If this setting is not enabled, after making a styling change, you can reload the app with a three-finger tap.

If Enable developer mode is enabled, and changes are made in the JavaScript styling files, the app automatically reloads with the new styling.

For more information, see the Getting the Make It Native App Reference Guide.

File and Folder Structure

Mendix offers a modular and flexible approach for styling apps. Styling can be done on an app level for app-specific styling, and styling can be put in modules for re-use.

To facilitate app- and module-level styling, the following file and folder structure is used; the theme folder is used for app-specific styling and the themesource folder is used for re-usable module styling and resources.

The bullets below describe the file structure for the theme folder and for modules:

theme
- web – This folder contains app specific styling resources for (progressive) web apps.
  - custom-variables.scss – This file contains the theme options (SASS variables) and lists the theme settings (CSS variables in a :root block) which can be overridden to easily change colors, font, spacing etc.
  - main.scss – This file is the starting point for adding custom styling.
  - exclusion-variables.scss – This file contains variables that can be toggled to optionally exclude Atlas core styling.
  - settings.json – This file contains the (external) CSS files that should be loaded. This includes the CSS result of the SASS compilation.
- native – This folder contains app specific styling resources for native mobile apps.
  - custom-variables.js – This file contains the theme setting which can be configured to easily change colors, font, spacing etc.
  - main.js – This file is the starting point for adding custom styling.
  - exclusion-variables.js – This file contains variables that can be toggled to optionally exclude Atlas core styling.
themesource – This folder contains module specific styling and resources. Every module has a folder that can contain styling resources.
- Atlas_core (required) – This folder from the Atlas core module which is the core for all Mendix apps. This module should always be part of an app as other modules depend on this and it contains all the styling for the Mendix widget. The content of this folder should not be changed as that will cause issues with migrating/updating to newer versions. For information about disabling default styling from this module see Disabling Default Styling below.
  - web – This folder (and subfolders) contain the web resources for the standard Mendix supported widgets.
    - themes/_theme-default.scss – This file contains all the theme settings (CSS variables) with their default values. Use it as a reference for the variables that can be overridden in your app.
    - design-properties.json – This file contains the design properties for the standard Mendix supported widgets.
  - native – This folder (and subfolders) contain the native mobile resources for the standard Mendix supported widgets.
  - public – This folder contains the font files of the default font.
- {MODULE_NAME} – Per module a folder is created which can contain styling resources for (progressive) web apps and native mobile apps.
  - web – This folder contains re-usable web resources
    - main.scss – This file is the starting point for the module web based styling.
    - design-properties.json – This file contains additional design properties or additional options for existing design properties that are based on the classes defined in this module.
  - native – This folder contains re-usable native mobile resources.
    - main.js – This file is the starting point for the module native mobile based styling.
    - design-properties.json – This file contains additional design properties or additional options for existing design properties that are based on the classes defined in this module.
  - public – This folder can contain other re-usable resources like a custom login.html page or images and fonts used from your web styling.

Styling output

With the modular structure of the styling of Mendix app, the styling files are placed in different folders. Studio Pro automatically combines the files to a single output (stylesheet for web and JavaScript for native) which is used by the app in the browser or on the device. The following sections describe in more detail how this is done.

Web Apps

Studio Pro combines the different .scss files in a certain order and compiles the SASS into CSS which is used in the browser. The compiled output is saved in a folder named theme-cache.

The content of this folder is regenerated regularly (for example when opening the app or pressing F4) and therefore should not be changed manually. Also note, that the theme-cache folder is included when uploading your app to the Team Server.

If a module contains styling, such as a design system module, it is generally best practice to mark the module as a UI resources module. This will make it possible to explicitly set a compilation order in the theme settings. For more information, see the Create a Theme Module section above.

The .scss files compile in the following order:

The main.scss files from the themesource folders, specifically:
1. Non-UI Marketplace modules, in alphabetical order.
2. UI resources modules, ordered as in App Settings > Theme.
3. Non-UI user modules, ordered as in the Studio Pro App explorer.
Custom variables from the theme folder (theme/web/custom-variables.scss).
main.scss from the theme folder (theme/web/main.scss).

The theme settings follow the same principle. Atlas Core first declares the default value of every CSS variable, and theme/web/main.scss is included last. Because a later declaration of a CSS variable replaces an earlier one, the theme settings in a file that is imported in main.scss take precedence over the defaults.

If SASS compilation fails, it will be shown in Studio Pro as a consistency error. This error gives information on what went wrong and what should be fixed:

The content from the public folder will be copied to the same folder as the theme.compiled.css file when deployed. This allows you to reference those resources using a relative path in the theme module's SCSS. For example, to use the image themesource/{module}/public/images/login-background.jpg from themesource/{module}/web/main.scss, you can simply use url("./images/login-background.jpg").

Note that public folders will be copied in the same order .scss files are compiled. Therefore if two modules have the same public resource, the last to be copied will end up in the deployment folder.

Native Mobile Apps

For native mobile apps the React Native framework is used to combine all the JavaScript files into one file, using a "bundler" that is responsible for creating the JavaScript bundle used to run the app. The styling of the different modules is combined and made ready to be processed by the bundler in the following order:

All main.js files from the themesource folders in the following order:
1. Non-UI Marketplace modules, in alphabetical order.
2. UI resources modules, ordered as in App Settings > Theme.
3. Non-UI user modules, ordered as in Studio Pro.
main.js from theme folder (theme/native/main.js).
Original styles.js in the theme folder if it exists (theme/styles.js).

If there are errors during the bundling, these will be shown in Studio Pro and the Make it Native app. For details on the error, it can be helpful to look at the native packager logs in {Mendix app directory}/deployment/log/native_packager_log.txt.

For more details on styling native mobile apps see the Native Mobile Styling Reference Guide.

Disabling default styling from Atlas Core

Mendix provides styling for the platform supported widgets in the Atlas core module. In general, for every widget there is base styling to provide a default look and feel for the widget and helper styling, which can be seen as additional styling and variations that can be used to fit the widget into its context. Styling can be overridden, but in some cases it can be preferred to disable this default styling. This is possible by excluding styling using variables which can be set in the exclusion variables file.

To disable the default styling of a web widget, open the exclusion-variables.scss file located in the folder {Mendix app}/theme/web. This file contains supported exclusion variables. The exclusion variables are SASS variables, not CSS variables, because they decide which styling is compiled into the stylesheet. Note that these variables can be part of a custom theme module as well, just like the custom variables as described in Create a Theme Module, by making the exclusion-variables.scss file in the app specific theme folder point to the exclusion variables file in your theme module.

Pick the button widget as an example. The success button is by default styled as in Figure 1:

Figure 1 - All Styles Enabled

To exclude additional styles, like the success button styles, the button helper styles need to be disabled. This can be achieved by setting the variable $exclude-button-helpers to true:

$exclude-button-helpers: true;

The resulting success button is visible in Figure 2:

Figure 2 - Helper Styles Disabled

To remove the complete default look and feel, both base and helper styles need to be disabled. This can be achieved by setting the variable $exclude-button to true as well:

$exclude-button: true;
$exclude-button-helpers: true;

It is not necessary to set both variables to true to exclude all styles, since Atlas automatically excludes helper styles when the base styles are excluded. Additional styles are useless when base styles are missing. Therefore, the following configuration is equivalent to the previous one:

$exclude-button: true;
$exclude-button-helpers: false;

The resulting success button is visible in Figure 3. Note that the underlying Bootstrap styles, the styles that the Atlas UI Framework is build upon, have become visible now.

Figure 3 - All Styles Disabled (visible Bootstrap styles)

All supported exclusion variables for web are:

$exclude-bootstrap
$exclude-mxui
$exclude-animations
$exclude-flex
$exclude-spacing
$exclude-base
$exclude-login
$exclude-accordion
$exclude-accordion-helpers
$exclude-background-helpers
$exclude-badge
$exclude-badge-button
$exclude-badge-button-helpers
$exclude-barcode-scanner
$exclude-button
$exclude-button-helpers
$exclude-card
$exclude-check-box
$exclude-check-box-radio-button
$exclude-combobox
$exclude-custom-dijit-widget
$exclude-custom-switch
$exclude-data-grid
$exclude-data-grid-helpers
$exclude-data-view
$exclude-data-picker
$exclude-demo-user-switcher
$exclude-div-container
$exclude-focus-ring
$exclude-glyphicon
$exclude-grid
$exclude-group-box
$exclude-group-box-helpers
$exclude-header
$exclude-helper-classes
$exclude-input
$exclude-image-helpers
$exclude-label
$exclude-label-helpers
$exclude-layout-grid
$exclude-list-view
$exclude-list-view-helpers
$exclude-modal
$exclude-navigation-bar
$exclude-navigation-bar-helpers
$exclude-navigation-list
$exclude-navigation-tree
$exclude-navigation-tree-helpers
$exclude-pagination
$exclude-pop-up-menu
$exclude-progress
$exclude-progress-bar
$exclude-progress-bar-helpers
$exclude-progress-circle
$exclude-progress-circle-helpers
$exclude-radio-button
$exclude-range-slider
$exclude-range-slider-helpers
$exclude-rating
$exclude-rating-helpers
$exclude-scroll-container
$exclude-simple-menu-bar
$exclude-simple-menu-bar-helpers
$exclude-slider
$exclude-slider-helpers
$exclude-table
$exclude-table-helpers
$exclude-tab-container
$exclude-tab-container-helpers
$exclude-template-grid
$exclude-template-grid-helpers
$exclude-timeline
$exclude-tooltip
$exclude-typography
$exclude-typography-helpers
$exclude-layout-atlas
$exclude-layout-atlas-phone
$exclude-layout-atlas-responsive
$exclude-layout-atlas-tablet

To disable the default styling of a native mobile widget, open the exclusion-variables.js file located in the folder {Mendix app}/theme/native. This file contains supported exclusion variables. Note that these variables can be part of a custom theme module as well, just like the custom variables as described in Create a Theme Module, by making the exclusion-variables.js file in the app specific theme folder point to the exclusion variables file in your theme module.

Pick the button widget as an example again. The success button is by default styled as in Figure 4.

Figure 4 - All Styles Enabled

To exclude additional styles, like the success button styles, the button helper styles need to be disabled. This can be achieved by setting the constant variable excludeButtonsHelpers to true:

export const excludeButtonsHelpers = true;

The resulting success button is visible in Figure 5.

Figure 5 - Helper Styles Disabled

Also for native mobile widgets both base and helper styles need to be disabled, to remove the complete Atlas look and feel. This can be achieved by setting the variable excludeButtons to true as well:

export const excludeButtons = true;
export const excludeButtonsHelpers = true;

export const excludeButtons = true;
export const excludeButtonsHelpers = false;

The resulting success button is visible in Figure 6. Note that the button text is white and, thus, not visible.

Figure 6 - All Styles Disabled (Button Text is White)

All supported exclusion variables for native mobile are:

excludeActivityIndicator
excludeActivityIndicatorHelpers
excludeAnimation
excludeBackgroundImage
excludeBadge
excludeBadgeHelpers
excludeBottomSheet
excludeButtons
excludeButtonsHelpers
excludeCarousel
excludeCheckBox
excludeColorPicker
excludeContainer
excludeDatePicker
excludeDropDown
excludeFeedback
excludeFAB
excludeFABHelpers
excludeImage
excludeImageHelpers
excludeIntroScreen
excludeIntroScreenHelpers
excludeLayoutGrid
excludeLineChart
excludeLineChartHelpers
excludeBarChart
excludeBarChartHelpers
excludeListView
excludeListViewHelpers
excludeListViewSwipe
excludeListViewSwipeHelpers
excludeMaps
excludeMapsHelpers
excludePageTitle
excludeProgressBar
excludeProgressBarHelpers
excludeProgressCircle
excludeProgressCircleHelpers
excludePopUpMenu
excludeQRCode
excludeRangeSlider
excludeRangeSliderHelpers
excludeRating
excludeReferenceSelector
excludeSafeAreaView
excludeSlider
excludeSliderHelpers
excludeTabContainer
excludeTabContainerHelpers
excludeTextArea
excludeTextBox
excludeTextBoxHelpers
excludeToggleButtons
excludeTypography
excludeTypographyHelpers
excludeVideoPlayer
excludeWebView
excludeHelpers

Customizing index.html (Web)

By default, Mendix generates the index.html (the page that is loaded to start the app) based on the app configuration. In some cases it may be needed to customize this HTML, which can be done by creating a file called index.html in the theme/web folder. To make sure that your file has the right structure, Mendix recommends copying index-example.html from the deployment/web folder to the theme/web, rename it to index.html, and then use it as a starting point. This file will be created after you have deployed your app locally at least once.

Cache Busting in Mendix

Cache busting is where a browser is told by the web server to re-download page resources (such as images, stylesheets, or JavaScript) because of changes in those resources. Mendix automatically takes care of this by adding dynamic query parameters on top of the resources in login.html and index.html. Here is an example of the auto-generated cachebust query parameters in a line from /deployment/web/index.html:

<script src="mxclientsystem/mxui/mxui.js?638184496048312490"></script>

Mendix is able to add the ?638184496048312490 query parameter because of the use of a dynamic parameter called {{cachebust}} in /deployment/web/index-example.html, which looks like this:

<script src="mxclientsystem/mxui/mxui.js?{{cachebust}}"></script>

When the Mendix React Client is enabled, the line in /deployment/web/index.html is as follows:

<script src="dist/index.js?{{cachebust}}" type="module"></script>

To ensure cache busting keeps working, whenever you need to customize index.html or login.html, make sure these files are copied according to the recommendations in Customizing index.html. Whenever cache busting breaks, it is likely that the query parameters have become hard coded (for example ?638184496048312490) instead of dynamic (for example ?{{cachebust}}) due to copying /deployment/web/index.html instead of the correct filename /deployment/web/index-example.html.

Customizing Unsupported Browsers (Web)

When an end-user opens a Mendix app in an unsupported browser, a page is shown that the current browser is not supported and explain which other browsers can be used. To customize this screen, you can create a custom html file called unsupported-browser.html in the theme/web folder. If desired, you can copy unsupported-browser.html from the deployment/web folder to the theme/web folder and use it as a starting point. This file will be created after you have deployed your app locally at least once.

Serving Fonts Locally (Web)

By default, Atlas uses the font Poppins. The font files are part of the Atlas Core module (themesource/atlas_core/public/resources/fonts/poppins) and are served by your own app. No font files are loaded from an external Content Delivery Network (CDN), which helps you comply with stricter CSP policies.

Using a Different Font

To use a different font and serve it from your own app, do the following:

Place the font files in a fonts folder inside the theme/web folder of your Mendix app.

In the same fonts folder, create a CSS file that declares the font with @font-face rules, for example theme/web/fonts/my-font.css:

@font-face {
    font-family: "My Font";
    src: url("./my-font-regular.woff2") format("woff2");
    font-weight: 400;
    font-style: normal;
}

Open your Mendix app's theme/web/custom-variables.scss file and locate the following line:
```
$font-family-import: false;
```
Replace that line with the following code, so that the CSS file from step 2 is loaded:
```
$font-family-import: "./fonts/my-font.css";
```
In the :root block of your theme file, set the font as the default font of your app:
```
:root {
    --font-family-base: "My Font", sans-serif;
}
```

Then, save your changes. Run your app and you should see the new font rendered correctly.

Customize Styling

Introduction

Changing the App Look and Feel

Changing the Default Theme Settings

Using Color Shades

Using the Styling Editor

Adding Custom Styling

Web Environment Example

Native Environment Example

Adding a Theme Variant (Web Only)

Importing CSS (Web Only)

Creating Re-Usable Styling

Creating a Theme Module

Marking as a UI Resources Module

Ordering UI Resource Modules

Examples

Web

Native Mobile

Previewing a Styling Change

Web apps

Native Mobile Apps

File and Folder Structure

Styling output

Web Apps

Native Mobile Apps

Disabling default styling from Atlas Core

Disabling Default Web Widget Styling

Disabling Default Native Mobile Widget Styling

Customizing index.html (Web)

Cache Busting in Mendix

Customizing Unsupported Browsers (Web)

Serving Fonts Locally (Web)

Using a Different Font

Feedback