ScrollViewer

ScrollViewer is a simple layout container that stretches to fill its parent's viewport and provides customizable scrollbar styles for scrollable content. It supports four scrollbar modes: normal (standard browser scrollbars), overlay (themed scrollbars always visible), whenMouseOver (scrollbars appear on hover), and whenScrolling (scrollbars appear during scrolling).

ScrollViewer is a layout container component that provides customizable scrollbar styling for its content. It stretches to fill 100% of its parent container's width and height, making it ideal for creating scrollable regions with enhanced visual control over scrollbar appearance.

Key features:

• Multiple scrollbar styles: Choose from browser default, themed, hover-activated, or scroll-activated scrollbars
• Automatic sizing: Stretches to fill parent container dimensions
• Theme integration: Uses shared theme variables for consistent styling across the application
• Performance optimized: Leverages OverlayScrollbars library for smooth, customizable scrolling

ScrollStyle Options:

The scrollStyle property controls how scrollbars are displayed:

• normal: Uses the browser's native default scrollbar
• overlay: Displays a themed scrollbar that is always visible and customizable via theme variables
• whenMouseOver: Shows the scrollbar only when hovering over the scroll container
• whenScrolling: Displays the scrollbar only while scrolling, then fades out after 400ms of inactivity

Basic Usage:

<App scrollWholePage="false">
  <ScrollViewer height="300px">
    <Items data="{ Array.from({ length: 50 }).map((_, i) => ('Item #' + i)) }">
      <Text value="{$item}" />
    </Items>
  </ScrollViewer>
</App>

Normal Scrollbar (Browser Default):

Overlay Scrollbar (Always Visible, Themed):

The overlay scrollbar is always visible and uses theme variables for customization.

When Mouse Over (Hover-Activated):

The scrollbar appears only when you hover your mouse over the scroll container.

When Scrolling (Scroll-Activated):

The scrollbar appears only while actively scrolling and fades out after 400ms of inactivity.

With Custom Content:

ScrollViewer works with any content type, not just lists.

%-PROP-START headerTemplate

The headerTemplate property allows you to define a custom header that remains fixed at the top of the ScrollViewer.

<App scrollWholePage="false">
  <ScrollViewer height="300px" backgroundColor="$color-surface-100">
    <property name="headerTemplate">
      <HStack 
        padding="$space-2" 
        backgroundColor="$color-surface-200" 
        borderBottom="1px solid $color-border-default"
      >
        <H4 value="Sticky Header" />
      </HStack>
    </property>
    <Items
      id="myList"
      data="{ Array.from({ length: 100 }).map((_, i) => ('Item #' + i)) }"
    >
      <Text value="{$item}" padding="$space-2" />
    </Items>
  </ScrollViewer>
</App>

<App scrollWholePage="false">
  <ScrollViewer height="300px" backgroundColor="$color-surface-100">
    <property name="headerTemplate">
      <HStack 
        padding="$space-2" 
        backgroundColor="$color-surface-200" 
        borderBottom="1px solid $color-border-default"
      >
        <H4 value="Sticky Header" />
      </HStack>
    </property>
    <Items
      id="myList"
      data="{ Array.from({ length: 100 }).map((_, i) => ('Item #' + i)) }"
    >
      <Text value="{$item}" padding="$space-2" />
    </Items>
  </ScrollViewer>
</App>

%-PROP-END

%-PROP-START footerTemplate

The footerTemplate property allows you to define a custom footer that remains fixed at the bottom of the ScrollViewer.

<App scrollWholePage="false">
  <ScrollViewer height="300px" backgroundColor="$color-surface-100">
    <Items
      id="myList"
      data="{ Array.from({ length: 100 }).map((_, i) => ('Item #' + i)) }"
    >
      <Text value="{$item}" padding="$space-2" />
    </Items>
    <property name="footerTemplate">
      <HStack 
        padding="$space-2" 
        backgroundColor="$color-surface-200" 
        borderTop="1px solid $color-border-default"
        horizontalAlignment="center"
      >
        <H4 value="Sticky Footer" />
      </HStack>
    </property>
  </ScrollViewer>
</App>

<App scrollWholePage="false">
  <ScrollViewer height="300px" backgroundColor="$color-surface-100">
    <Items
      id="myList"
      data="{ Array.from({ length: 100 }).map((_, i) => ('Item #' + i)) }"
    >
      <Text value="{$item}" padding="$space-2" />
    </Items>
    <property name="footerTemplate">
      <HStack 
        padding="$space-2" 
        backgroundColor="$color-surface-200" 
        borderTop="1px solid $color-border-default"
        horizontalAlignment="center"
      >
        <H4 value="Sticky Footer" />
      </HStack>
    </property>
  </ScrollViewer>
</App>

%-PROP-END

Behaviors

This component supports the following behaviors:

Properties

footerTemplate

An optional template that defines content always visible at the bottom of the ScrollViewer, outside the scrollable area. The footer sticks to the bottom while the inner content scrolls.

The footerTemplate property allows you to define a custom footer that remains fixed at the bottom of the ScrollViewer.

<App scrollWholePage="false">
  <ScrollViewer height="300px" backgroundColor="$color-surface-100">
    <Items
      id="myList"
      data="{ Array.from({ length: 100 }).map((_, i) => ('Item #' + i)) }"
    >
      <Text value="{$item}" padding="$space-2" />
    </Items>
    <property name="footerTemplate">
      <HStack 
        padding="$space-2" 
        backgroundColor="$color-surface-200" 
        borderTop="1px solid $color-border-default"
        horizontalAlignment="center"
      >
        <H4 value="Sticky Footer" />
      </HStack>
    </property>
  </ScrollViewer>
</App>

<App scrollWholePage="false">
  <ScrollViewer height="300px" backgroundColor="$color-surface-100">
    <Items
      id="myList"
      data="{ Array.from({ length: 100 }).map((_, i) => ('Item #' + i)) }"
    >
      <Text value="{$item}" padding="$space-2" />
    </Items>
    <property name="footerTemplate">
      <HStack 
        padding="$space-2" 
        backgroundColor="$color-surface-200" 
        borderTop="1px solid $color-border-default"
        horizontalAlignment="center"
      >
        <H4 value="Sticky Footer" />
      </HStack>
    </property>
  </ScrollViewer>
</App>

headerTemplate

An optional template that defines content always visible at the top of the ScrollViewer, outside the scrollable area. The header sticks to the top while the inner content scrolls.

The headerTemplate property allows you to define a custom header that remains fixed at the top of the ScrollViewer.

<App scrollWholePage="false">
  <ScrollViewer height="300px" backgroundColor="$color-surface-100">
    <property name="headerTemplate">
      <HStack 
        padding="$space-2" 
        backgroundColor="$color-surface-200" 
        borderBottom="1px solid $color-border-default"
      >
        <H4 value="Sticky Header" />
      </HStack>
    </property>
    <Items
      id="myList"
      data="{ Array.from({ length: 100 }).map((_, i) => ('Item #' + i)) }"
    >
      <Text value="{$item}" padding="$space-2" />
    </Items>
  </ScrollViewer>
</App>

<App scrollWholePage="false">
  <ScrollViewer height="300px" backgroundColor="$color-surface-100">
    <property name="headerTemplate">
      <HStack 
        padding="$space-2" 
        backgroundColor="$color-surface-200" 
        borderBottom="1px solid $color-border-default"
      >
        <H4 value="Sticky Header" />
      </HStack>
    </property>
    <Items
      id="myList"
      data="{ Array.from({ length: 100 }).map((_, i) => ('Item #' + i)) }"
    >
      <Text value="{$item}" padding="$space-2" />
    </Items>
  </ScrollViewer>
</App>

scrollStyle

default: "normal"

This property determines the scrollbar style and behavior. normal uses the standard browser scrollbar. overlay uses themed scrollbars that are always visible and can be customized via theme variables. whenMouseOver shows overlay scrollbars that appear when the mouse hovers over the scroll area and hide after 200ms when the mouse leaves. whenScrolling shows overlay scrollbars only during active scrolling and hides them after 400ms of inactivity.

Available values: normal (default), overlay, whenMouseOver, whenScrolling

showScrollerFade

default: true

When enabled, displays gradient fade indicators at the top and bottom of the scroll container to visually indicate that more content is available in those directions. The fade indicators automatically appear/disappear based on the current scroll position. Top fade shows when scrolled down from the top, bottom fade shows when not at the bottom. Only works with overlay scrollbar modes (not with normal mode).

Events

This component does not have any events.

Exposed Methods

This component does not expose any methods.

Styling

The ScrollViewer component uses shared theme variables with other layout containers that may act as scroll containers. Please note that these shared theme variables use the Scroller virtual component name, and not ScrollViewer.

Theme Variables

Variable Explanations