sidePanelLayout

sidePanelLayout adds a panel that opens beside or over the main content.

A side panel can also be created programmatically using Side Dialog.

XML Element	`sidePanelLayout`
Java Class	`SidePanelLayout`

XML Element

sidePanelLayout

Java Class

SidePanelLayout

Basics

SidePanelLayout divides the content into two areas:

Main content – the primary layout area.
Side panel content – a panel that slides in from one side.

To define the component in XML, use the sidePanelLayout element and add exactly two direct child components.

<sidePanelLayout id="sidePanelLayout"
                 width="100%"
                 height="100%">

    <vbox id="contentBox">
        <!-- Main content -->
    </vbox>

    <vbox id="sidePanelBox" width="100%" height="100%">

        <hbox id="headerBox" width="100%"> (1)
            <h2 text="Customer information"/>
            <sidePanelLayoutCloser/>
        </hbox>

        <!-- Side panel content -->

    </vbox>
</sidePanelLayout>

A side panel typically includes a close button. Use the dedicated sidePanelLayoutCloser component to add that button.

Opening the Side Panel

The side panel opens in response to user actions such as clicking a button. Call the toggleSidePanel() method:

@ViewComponent
private SidePanelLayout sidePanelLayout;

@Subscribe(id = "toggleButton", subject = "clickListener")
public void onToggleButtonClick(final ClickEvent<JmixButton> event) {
    sidePanelLayout.toggleSidePanel();
}

Resizing the Side Panel

Since Jmix 3.1

Set the sidePanelResizable attribute to true to let users resize the side panel by dragging the handle on its inner edge.

<facets>
    <settings auto="true"/>
</facets>
    <sidePanelLayout id="sidePanelLayout"
                     width="100%"
                     height="100%"
                     sidePanelResizable="true">
        <!-- ... -->
    </sidePanelLayout>
</layout>

For the LEFT, RIGHT, INLINE_START, and INLINE_END positions, dragging changes the panel width. For the TOP and BOTTOM positions, it changes the panel height. The size remains within the limits defined by the corresponding minimum and maximum size attributes.

To save and restore the size selected by the current user, add the settings facet and set its auto attribute to true. A saved size overrides the initial size defined in XML. Horizontal and vertical sizes are stored independently.

Side Panel Editor

Use SidePanelLayout for a master-detail pattern where the main area contains a list of entities and the side panel edits the selected instance.

Styling

You can customize the appearance and size of SidePanelLayout using CSS variables and theme selectors.

Sizing with CSS Variables

The following variables define the side panel size. Set them globally or in a selector that targets a particular sidePanelLayout.

Values set in XML or using the Java API override CSS variables.

Horizontal side panels (LEFT, RIGHT, INLINE_START, INLINE_END):

Variable	Description	Default
`--jmix-side-panel-layout-horizontal-size`	Preferred width of the side panel.	`auto`
`--jmix-side-panel-layout-horizontal-max-size`	Maximum width.	`50%`
`--jmix-side-panel-layout-horizontal-min-size`	Minimum width.	`14em`

Variable

Description

Default

--jmix-side-panel-layout-horizontal-size

Preferred width of the side panel.

auto

--jmix-side-panel-layout-horizontal-max-size

Maximum width.

50%

--jmix-side-panel-layout-horizontal-min-size

Minimum width.

14em

Vertical side panels (TOP, BOTTOM):

Variable	Description	Default
`--jmix-side-panel-layout-vertical-size`	Preferred height of the side panel.	`auto`
`--jmix-side-panel-layout-vertical-max-size`	Maximum height.	`50%`
`--jmix-side-panel-layout-vertical-min-size`	Minimum height.	`10em`

Variable

Description

Default

--jmix-side-panel-layout-vertical-size

Preferred height of the side panel.

auto

--jmix-side-panel-layout-vertical-max-size

Maximum height.

50%

--jmix-side-panel-layout-vertical-min-size

Minimum height.

10em

Resize Handle

Since Jmix 3.1

The resize handle uses the following CSS variables. Their default values match the current theme’s SplitLayout splitter and can change when the resizer-small theme variant is applied.

Variable	Description
`--jmix-side-panel-layout-splitter-size`	Width of a vertical splitter or height of a horizontal splitter.
`--jmix-side-panel-layout-splitter-target-size`	Size of the pointer target across the splitter.
`--jmix-side-panel-layout-splitter-background`	Splitter background.
`--jmix-side-panel-layout-handle-size`	Thickness of the grip inside the splitter.
`--jmix-side-panel-layout-handle-target-size`	Length of the grip inside the splitter.
`--jmix-side-panel-layout-handle-background`	Grip background.

Variable

Description

--jmix-side-panel-layout-splitter-size

Width of a vertical splitter or height of a horizontal splitter.

--jmix-side-panel-layout-splitter-target-size

Size of the pointer target across the splitter.

--jmix-side-panel-layout-splitter-background

Splitter background.

--jmix-side-panel-layout-handle-size

Thickness of the grip inside the splitter.

--jmix-side-panel-layout-handle-target-size

Length of the grip inside the splitter.

--jmix-side-panel-layout-handle-background

Grip background.

Appearance

Variable	Description	Default
`--jmix-side-panel-layout-transition-duration`	Controls how long the open and close animation takes.	`200ms`

Variable

Description

Default

--jmix-side-panel-layout-transition-duration

Controls how long the open and close animation takes.

200ms

Parts

SidePanelLayout exposes the following stylable parts:

Part	Description
`jmix-side-panel-layout::part(layout)`	Container for content, side panel, and modality curtain.
`jmix-side-panel-layout::part(content)`	Main layout content.
`jmix-side-panel-layout::part(modalityCurtain)`	Modality curtain.
`jmix-side-panel-layout::part(sidePanel)`	Panel that moves into and out of view.
`jmix-side-panel-layout::part(sidePanelContent)`	Side panel content container.
`jmix-side-panel-layout::part(resizeHandle)`	Resize handle on the inner edge of the side panel.

Part

Description

jmix-side-panel-layout::part(layout)

Container for content, side panel, and modality curtain.

jmix-side-panel-layout::part(content)

Main layout content.

jmix-side-panel-layout::part(modalityCurtain)

Modality curtain.

jmix-side-panel-layout::part(sidePanel)

Panel that moves into and out of view.

jmix-side-panel-layout::part(sidePanelContent)

Side panel content container.

jmix-side-panel-layout::part(resizeHandle)

Resize handle on the inner edge of the side panel.

States

The component exposes the following states:

State	Description
`jmix-side-panel-layout[side-panel-opened]`	Applied when the side panel is open.
`jmix-side-panel-layout[modal]`	Applied when the side panel is modal.
`jmix-side-panel-layout[side-panel-position='left']`	Matches the current side panel position (`right`, `top`, and so on).
`jmix-side-panel-layout[side-panel-overlay]`	Applied when the panel overlays content instead of pushing it.
`jmix-side-panel-layout[side-panel-resizable]`	Applied when user resizing is enabled.
`jmix-side-panel-layout[resizing]`	Applied while the user is dragging the resize handle.

State

Description

jmix-side-panel-layout[side-panel-opened]

Applied when the side panel is open.

jmix-side-panel-layout[modal]

Applied when the side panel is modal.

jmix-side-panel-layout[side-panel-position='left']

Matches the current side panel position (right, top, and so on).

jmix-side-panel-layout[side-panel-overlay]

Applied when the panel overlays content instead of pushing it.

jmix-side-panel-layout[side-panel-resizable]

Applied when user resizing is enabled.

jmix-side-panel-layout[resizing]

Applied while the user is dragging the resize handle.

Attributes

Common attributes serve the same purpose for all components. The following attributes are specific to sidePanelLayout.

Name Description Default

Name	Description	Default
sidePanelPosition	Defines the side from which the panel appears. Possible values are `LEFT`, `RIGHT`, `TOP`, `BOTTOM`, `INLINE_START`, and `INLINE_END`. `INLINE_START` and `INLINE_END` follow the reading direction of the page (LTR or RTL).	`RIGHT`
sidePanelOverlay	Determines how the side panel interacts with the main content. If `true`, the panel overlays the content without changing its layout. If `false`, the panel pushes the content aside as it opens.	`true`
modal	When `true` a modality curtain appears behind the side panel and prevents interaction with the main content until the panel is closed.	`true`
closeOnOutsideClick	When `true`, clicking the modality curtain closes the side panel. This attribute only has an effect when modal is enabled.	`true`
overlayAriaLabel	Sets the accessible label for the overlay element.	—
displayAsOverlayOnSmallDevices	If `true`, the side panel is displayed as a full-screen overlay on small devices, ensuring that the content remains usable on mobile layouts.	`true`
sidePanelResizable	If `true`, the user can resize the side panel by dragging the handle on its inner edge. The panel remains within the minimum and maximum size limits. The resize handle is not displayed when the panel switches to a full-screen overlay on small devices. Since Jmix 3.1	`false`
sidePanelHorizontalSize	Defines the width of the side panel when its position is `LEFT`, `RIGHT`, `INLINE_START`, or `INLINE_END`. The value can be any valid CSS size such as `400px`, `30%`, or `auto`.	`auto`
sidePanelHorizontalMinSize	Defines the minimum width of a horizontally positioned side panel.	`14em`
sidePanelHorizontalMaxSize	Defines the maximum width of a horizontally positioned side panel.	`50%`
sidePanelVerticalSize	Defines the vertical size of the side panel when it appears from the top or bottom.	`auto`
sidePanelVerticalMinSize	Defines the minimum vertical size of the side panel.	`10em`
sidePanelVerticalMaxSize	Defines the maximum vertical size of the side panel.	`50%`

sidePanelPosition

Defines the side from which the panel appears. Possible values are LEFT, RIGHT, TOP, BOTTOM, INLINE_START, and INLINE_END.

INLINE_START and INLINE_END follow the reading direction of the page (LTR or RTL).

RIGHT

sidePanelOverlay

Determines how the side panel interacts with the main content.

If true, the panel overlays the content without changing its layout. If false, the panel pushes the content aside as it opens.

true

modal

When true a modality curtain appears behind the side panel and prevents interaction with the main content until the panel is closed.

true

closeOnOutsideClick

When true, clicking the modality curtain closes the side panel.

This attribute only has an effect when modal is enabled.

true

overlayAriaLabel

Sets the accessible label for the overlay element.

—

displayAsOverlayOnSmallDevices

If true, the side panel is displayed as a full-screen overlay on small devices, ensuring that the content remains usable on mobile layouts.

true

sidePanelResizable

If true, the user can resize the side panel by dragging the handle on its inner edge. The panel remains within the minimum and maximum size limits. The resize handle is not displayed when the panel switches to a full-screen overlay on small devices.

Since Jmix 3.1

false

sidePanelHorizontalSize

Defines the width of the side panel when its position is LEFT, RIGHT, INLINE_START, or INLINE_END.

The value can be any valid CSS size such as 400px, 30%, or auto.

auto

sidePanelHorizontalMinSize

Defines the minimum width of a horizontally positioned side panel.

14em

sidePanelHorizontalMaxSize

Defines the maximum width of a horizontally positioned side panel.

50%

sidePanelVerticalSize

Defines the vertical size of the side panel when it appears from the top or bottom.

auto

sidePanelVerticalMinSize

Defines the minimum vertical size of the side panel.

10em

sidePanelVerticalMaxSize

Defines the maximum vertical size of the side panel.

50%

Handlers

Common handlers are configured in the same way for all components. The following handlers are specific to sidePanelLayout.

Name Description

Name	Description
ModalityCurtainClickEvent	Fires when the user clicks the modality curtain.
SidePanelBeforeOpenEvent	Fires before the side panel is displayed and before its opening animation starts. Use it to update content before the panel becomes visible.
SidePanelAfterOpenEvent	Fires after the side panel is fully open and its opening animation has finished.
SidePanelCloseEvent	Fires when the side panel closes.
SidePanelAfterResizeEvent	Fires once after the user finishes dragging the resize handle and the panel size has changed. The `getSize()` method returns the new width or height as a CSS length in pixels. Since Jmix 3.1

ModalityCurtainClickEvent

Fires when the user clicks the modality curtain.

SidePanelBeforeOpenEvent

Fires before the side panel is displayed and before its opening animation starts. Use it to update content before the panel becomes visible.

SidePanelAfterOpenEvent

Fires after the side panel is fully open and its opening animation has finished.

SidePanelCloseEvent

Fires when the side panel closes.

SidePanelAfterResizeEvent

Fires once after the user finishes dragging the resize handle and the panel size has changed. The getSize() method returns the new width or height as a CSS length in pixels.

Since Jmix 3.1

Elements

A sidePanelLayout contains exactly two root components: the main content and the side-panel content. Use sidePanelLayoutCloser inside the panel when it needs a dedicated close button.

Was this page helpful?

Thank you for your feedback

Something went wrong