Root Screens

A root screen is a Jmix UI screen that is displayed directly in the web browser tab. There are two types of such screens: login screen and main screen. Among other components, any root screen can contain the WorkArea component which enables opening other application screens in the inner tabs. If the root screen doesn’t contain WorkArea, application screens can be opened only in the DIALOG mode.

Login Screen

Login screen is displayed before a user logs in. You can customize the existing login screen by changing its descriptor and controller.

Also, you can use Login screen with branding image template in Studio wizard to create a new login screen. After creating, the identifier of the newly created screen will be set in the jmix.ui.login-screen-id property.

Main Screen

Main screen is a root application screen displayed when the user is logged in. By default, the framework provides the main screen with a collapsible side menu.

You can use the following types of main screens in your application:

  • Main screen with side menu. It allows users to expand and collapse the side menu using the Collapse button located in the lower-left corner.

  • Main screen with top menu. It contains a menu bar on the top of your application window. You can create this screen from a template using Studio wizard. After creating, the identifier of the newly created screen will be set in the jmix.ui.main-screen-id property.

The following special components may be used in the main screen in addition to the standard UI components:

  • SideMenu - application menu in the form of the vertical tree.

  • AppMenu - application menu bar.

  • Drawer - a panel that can be collapsed to the left side. This panel is used as a side menu container.

  • AppWorkArea - work area, the required component for opening screens in the THIS_TAB, NEW_TAB, and NEW_WINDOW modes.

  • NewWindowButton - the button which opens a new main screen in a separate browser tab.

  • TimeZoneIndicator - the label displaying the current user’s time zone.

  • UserIndicator - the field which displays the name of the current user.

    The setFormatter() method allows you to represent the user’s name in a format different from the User instance name:

    private UserIndicator userIndicator;
    public void onBeforeShow(BeforeShowEvent event) {
        userIndicator.setFormatter(value -> value.getUsername() + " - user");
  • LogoutButton - the application logout button.

The following application properties can affect the main screen: