Class AppHeadroom

java.lang.Object
com.vaadin.flow.component.Component
org.vaadin.addons.joelpop.appheadroom.ui.component.AppHeadroom
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasStyle, Serializable
@Tag("app-headroom") @JsModule("./app-headroom.ts") public class AppHeadroom extends com.vaadin.flow.component.Component
Hides/shows an AppLayout's top and bottom navigation bars on scroll.

This component only ever knows about AppLayout's own standard, public contract — specifically the navbar-top and navbar-bottom shadow-DOM parts every vaadin-app-layout instance exposes, regardless of subclass. It has no knowledge of, and no dependency on, any specific AppLayout extension (e.g. one that adds a persistent side rail): whatever a subclass does with those two standard parts, AppHeadroom finds and manages them the same way every time.

By default, a bar that's already pinned to the viewport (position: fixed) and shaped like a vertical rail rather than a horizontal bar (taller than wide) is left alone automatically — a plain, observable geometry fact, not something any extension has to declare. For cases where that inference isn't right (or an extension's own behavior can't be reliably inferred that way), setTopBarPinned(boolean) / setBottomBarPinned(boolean) let calling code state it explicitly instead. See those methods for how this is meant to be wired up from application code.

See Also:

  • Field Details

  • Method Details

    • applyTo

      public static AppHeadroom applyTo(com.vaadin.flow.component.applayout.AppLayout layout)
      Applies headroom scroll-hide/show behavior to the given AppLayout and returns the component for optional further configuration.

      The returned instance attaches itself as a peer under the current UI's root element, never as a light-DOM child of layout — so it never shows up in layout.getChildren(). This happens automatically whenever layout itself is attached (immediately, if it already is), and follows layout across any subsequent detach/re-attach. Call remove() to detach headroom behavior from layout without affecting the layout itself.

      The effect is active on every device by default; see setActivationPredicate(SerializableBiPredicate) to restrict it by device type/orientation.

    • remove

      public void remove()
      Detaches this instance, removing its scroll-hide/show behavior from the AppLayout it was applied to. Has no effect if already detached.

    • setTopOffset

      public AppHeadroom setTopOffset(int px)
      Sets the distance from the top of the page, in pixels, within which the chrome is always shown (default 100). Returns this for chaining.
      Throws:
      IllegalArgumentException - if px is negative

    • setHideTolerance

      public AppHeadroom setHideTolerance(int px)
      Sets how far, in pixels, the user must scroll down past the last shown-position high-water mark before the chrome hides (default 30). Returns this for chaining.
      Throws:
      IllegalArgumentException - if px is negative

    • setShowTolerance

      public AppHeadroom setShowTolerance(int px)
      Sets how far, in pixels, the user must scroll up past the last hidden-position low-water mark before the chrome is restored (default 30). Returns this for chaining.
      Throws:
      IllegalArgumentException - if px is negative

    • setTransitionDuration

      public AppHeadroom setTransitionDuration(int ms)
      Sets how long, in milliseconds, the show/hide slide and padding transitions take (default 600). Returns this for chaining.
      Throws:
      IllegalArgumentException - if ms is negative

    • setTopBarPinned

      public AppHeadroom setTopBarPinned(boolean pinned)
      Explicitly overrides whether the top bar is treated as pinned (never hidden), regardless of the automatic position/shape inference.

      Not called directly by any AppLayout extension — extensions have no reason to know AppHeadroom exists. Instead, this is meant to be wired up from application code that already explicitly combines an AppLayout extension with AppHeadroom (for example, code overriding an extension's own hook for observing layout-mode changes, if it has one), reacting to whatever that extension's own public API exposes about its current state and calling this method accordingly.

    • setBottomBarPinned

      public AppHeadroom setBottomBarPinned(boolean pinned)
      Same as setTopBarPinned(boolean), for the bottom bar.

    • isPinned

      @Synchronize("pinned-changed") public boolean isPinned()
      Whether the chrome is currently shown (true, the initial and default state) or hidden (false). Kept in sync with the client's own scroll-driven pin/unpin state; see addPinnedChangeListener(ComponentEventListener) to be notified of changes instead of polling this.

    • addPinnedChangeListener

      public com.vaadin.flow.shared.Registration addPinnedChangeListener(com.vaadin.flow.component.ComponentEventListener<AppHeadroom.PinnedChangeEvent> listener)
      Registers a listener to be notified whenever isPinned() changes.

    • onDetach

      protected void onDetach(com.vaadin.flow.component.DetachEvent detachEvent)
      Resets the server-visible pinned state directly, rather than relying on the client's own pinned-changed event during teardown: when detachment is server-initiated (e.g. layout.remove(headroom)), Flow stops routing further client events for this component the moment removal begins, so the client-fired event from disconnectedCallback() never reaches here.
      Overrides:
      onDetach in class com.vaadin.flow.component.Component

    • setActivationPredicate

      public AppHeadroom setActivationPredicate(com.vaadin.flow.function.SerializableBiPredicate<AppHeadroom.DeviceType, AppHeadroom.Orientation> predicate)
      Sets the predicate that decides whether the headroom effect should be active, evaluated against this session's detected AppHeadroom.DeviceType and current AppHeadroom.Orientation. Re-evaluated automatically whenever either becomes known or changes (e.g. on device rotation) — there's nothing further to wire up.

      The default predicate always returns true: the effect is active on every device unless this is called. There's no separate plain on/off switch — force it fully on or off yourself with (deviceType, orientation) -> true / -> false, or restrict it by device, e.g. to restore the original phone-always/tablet-landscape-only behavior this had before being extracted into this library: 

      AppHeadroom.applyTo(layout).setActivationPredicate((deviceType, orientation) ->
    deviceType == AppHeadroom.DeviceType.PHONE
        || (deviceType == AppHeadroom.DeviceType.TABLET && orientation == AppHeadroom.Orientation.LANDSCAPE));
      Returns:
      this, for chaining

    • setTabletMinShortSidePx

      public AppHeadroom setTabletMinShortSidePx(int px)
      Overrides the physical-screen-shorter-side threshold, in CSS pixels, used to distinguish AppHeadroom.DeviceType.TABLET from AppHeadroom.DeviceType.PHONE among touch devices (default 768, matching vaadin-flow-app-nav-layout's equivalent device detection).

      Must be called before the target AppLayout attaches to take effect — device type is detected once, at first attach, same as setActivationPredicate(SerializableBiPredicate)'s predicate is evaluated against whatever's known at the time.

      Returns:
      this, for chaining
      Throws:
      IllegalArgumentException - if px is negative

    • isActive

      public boolean isActive()
      Whether the headroom effect is currently active for this session, per the last evaluation of the activation predicate. Defaults to true until device type and orientation are both known (shortly after the target AppLayout attaches).