Responsiveness

A responsive view remains easy to understand and use as the available space changes. It should work in a resized desktop window, on a tablet or phone, and at every size in between.

Jmix provides much of the required behavior through standard views, layouts, and adaptable visual components. When more control is needed, use the techniques described below.

Built-in Responsiveness

Standard Jmix views combine layout and visual components that adapt to the available space and input method. For example:

  • The main menu collapses on a narrow screen.

  • On touchscreen devices, datePicker and select display their overlays at the bottom of the screen.

  • Dialog actions can stack vertically when horizontal space is limited.

  • tabSheet and tabs become scrollable.

  • formLayout can change the number of columns.

Designing Responsive Views

When building a responsive view from scratch start with a simple layout for the narrowest screen and add columns, context, or actions when more space is available. Use layout components before adding custom CSS.

Layouts

Layout components control how content grows, shrinks, and moves as the available space changes. Use formLayout for responsive forms. Use gridLayout to arrange components in a responsive grid. gridLayout fits as many columns as the available width allows and moves the remaining items onto new rows.

See Layout Rules for guidance on combining layouts and sizing their content.

CSS Media and Container Queries

A media query checks a condition, such as whether the browser window is wider than a given value, and applies a group of CSS rules only when the condition is true.

Use a media query when components and layouts cannot provide the required change. First, add a class name in the view descriptor:

<hbox classNames="view-toolbar" width="100%">
    <!-- Content -->
</hbox>

Then define the narrow layout and its wide-screen enhancement in the application theme CSS:

.view-toolbar {
    flex-direction: column;
    align-items: stretch;
}

@media (min-width: 48rem) {
    .view-toolbar {
        flex-direction: row;
        align-items: center;
    }
}

The 48rem value is a breakpoint – the width where the layout changes. Below 48rem, the controls are stacked and stretch to the full width. At 48rem and above, they are arranged horizontally and aligned vertically in the center. You can define several media queries when the layout needs more than one change.

Media queries use the width of the browser window. In a resizable content area, use a container query to apply CSS based on the width of the containing element instead. This lets a component adapt wherever it is placed.

Wrapping at In-between Sizes

At intermediate widths, components may share the available row space but not fit on a single line. Allow the row to wrap onto additional lines:

<hbox id="viewToolbar" width="100%" wrap="true">
    <!-- Content -->
</hbox>

In Java, call viewToolbar.setWrap(true).

Resize the browser slowly when testing. Check intermediate widths, browser zoom, split-screen windows, long translated labels, and both portrait and landscape orientation.

Lumo Utility Classes

Applications that use Lumo Theme can handle some common responsive changes with utility classes instead of custom CSS.

Apply the responsive classes in the view descriptor:

<hbox classNames="flex-col md:flex-row" width="100%">
    <!-- Content -->
</hbox>

In this example the layout starts as a column and changes to a row at the md breakpoint.

See Lumo utility classes for setup and the responsive utility class reference for the available breakpoints.

Dedicated Mobile Views

Whenever possible, use a single responsive view for both desktop and mobile. It is easier to maintain and provides consistent behavior across screen sizes. Some data-heavy views, however, cannot provide an equally effective desktop and mobile experience with one layout. Consider separate desktop and mobile views when both require a carefully polished interface or when the interaction is genuinely different. For example, field workers may need a shorter workflow with fewer actions, camera access, or swipe gestures.

Separate views increase development and maintenance work. Use fragments to reuse fields, forms, and other UI sections across the views and minimize duplicated presentation code. Keep shared business logic in services.

Jmix does not automatically choose between desktop and mobile views according to screen size. The application must open the appropriate view explicitly.

Designing Responsive Views for Mobile

If a dedicated mobile view is necessary, design it using the responsive patterns for regular views. Additionally, adapt common interactions for touch input and limited screen space.

Virtual List

On small screens, a dataGrid may require too much horizontal space and can be difficult to use with touch input. For lists where users open individual items, virtualList is usually a better fit. Use a fragment renderer to create a compact card layout for each item.

The Wind Turbines demo uses this pattern for its turbine list:

<virtualList itemsContainer="turbinesDc" width="100%">
    <fragmentRenderer class="io.jmix.windturbines.view.turbine.TurbineCard"/>
</virtualList>

Side Panels

Keep secondary elements out of the main workflow until the user needs them. A closable panel provides access without permanently occupying screen space. Use sidePanelLayout to add such a panel to the view descriptor. Use Side Dialog to create one from Java code.

Switch

switch is a touchscreen-friendly control for a binary setting. Use it when the application applies the setting immediately, without separate confirmation. Its larger control is easy to tap and can save screen space by eliminating an additional confirmation button.

Step-by-step Wizard

For long input forms, show one step at a time. Provide clear Back, Next, and Complete actions, and validate the current step before moving forward. This keeps the user focused and avoids a long page of fields.

Jmix does not have a dedicated wizard component. The Wizard sample builds this pattern with tabSheet for navigation and a fragment for each step.

Drag and Drop

Drag and drop can make moving, grouping, or reordering items more direct on a touch screen and can reduce the number of visible action buttons. Vaadin allows you to make components drag sources and drop targets. See the Drag and Drop cookbook.