Unlike a fixed panel, which stays at a constant position in the viewport, a sticky panel behaves like an ordinary component until scrolling reaches its configured position. It then remains at that position while its containing area continues scrolling.

This makes StickyPanel particularly useful for navigation bars, section headings, toolbars, and other interface elements that should remain accessible without being permanently fixed to the screen.

Overview

A StickyPanel contains another component, just like other JDance panels. You can set its content, configure its appearance, and specify the distance from the top of the viewport.

The following example creates a sticky heading.

CODE

Text heading = new Text("Sticky heading");

StickyPanel sticky = new StickyPanel();
sticky.setContent(heading);
sticky.setRelativeWidth(100);
sticky.setPadding(8);
sticky.setBackground(new Color("#DCEEFF"));
sticky.setViewportTopMargin(0);

BasicLayout layout = new BasicLayout(BasicLayout.Direction.VERTICAL);
layout.setRelativeWidth(100);
layout.add(sticky);
layout.add(new Text("Scroll the parent to observe sticky positioning.")).setPadding(8);

RESULT

Sticky heading

Scroll the parent to observe sticky positioning.

The example demonstrates how a StickyPanel is configured. Its sticky behavior becomes visible when the surrounding page or container has enough content to scroll.

How sticky positioning works

Sticky positioning combines the behavior of normal document flow and fixed positioning.

Initially, the panel occupies its ordinary position in the layout. As the user scrolls, it moves with the surrounding content.

When it reaches its configured offset, the browser keeps it at that position, subject to the boundaries of its containing area.

The important distinction is that StickyPanel is not permanently fixed to the viewport. It remains associated with its surrounding layout.

Positioning below a header

Many applications have a navigation bar or another element occupying the top of the screen.

In those cases, the sticky panel should not overlap the existing header.

You can configure a top margin to reserve that space.

CODE

StickyPanel sticky = new StickyPanel();
sticky.setContent(new Text("Navigation"));
sticky.setViewportTopMargin(60);

In this example, the panel is configured with a 60px top offset.

StickyPanel and scrolling containers

Sticky positioning depends on the surrounding layout and its scrolling behavior.

If an ancestor has its own scrolling area, sticky positioning may operate relative to that area instead of the browser window.

Properties such as overflow can also affect which ancestor controls sticky positioning.

This is especially important when building applications with nested layouts, sidebars, and independently scrollable content areas.

When a StickyPanel does not behave as expected, inspect the overflow settings of its parent layouts before changing the panel itself.

StickyPanel vs FixedPanel

StickyPanel and FixedPanel solve different interface problems.

StickyPanel is appropriate when a component should participate in the normal layout but remain visible after scrolling reaches a particular position.

FixedPanel is appropriate when a component should remain attached to a viewport position independently of the normal document flow.

For example, a section toolbar is a good candidate for StickyPanel, while a permanently visible floating control may be better implemented with FixedPanel.

Full API reference

This page demonstrates the fundamental behavior of StickyPanel and some common usage patterns.

For the complete API reference, including configuration methods and inherited functionality, visit https://doc.jdance.org.