Skip to content

ScrollArea

ScrollArea is a scrolling container with its own scroll bar. It scrolls with the mouse wheel and keeps moving after a flick. It stretches past the edge and springs back. You can run an action when the user pulls past the top, for example to refresh.

Usage

Call Components.ScrollArea with a scope and a table of properties:

C.ScrollArea(scope, {
    Size = UDim2.fromScale(1, 1),
    Children = {
        C.Text(scope, { Text = "Long content" }),
    },
    OnRefresh = function() -- (1)!
        reload()
    end,
})
  1. OnRefresh is called when the user pulls past the top and lets go. While the user pulls, a hint shows what will happen. It is not limited to refreshing.

Controls inside a scroll area

A control inside the area that follows a drag, such as a slider or a colour picker, keeps the drag to itself. The area does not scroll along with it.

Virtual content

To show a very long list, use VirtualList, which is built on ScrollArea. Set ContentLayout = "None" and ContentPadding = 0 if you place content yourself.

Properties

Name Type Required Default Description
Theme ThemeRef ❌ The contextual theme Theme to use for this component instead of the one from Theme.Provide.
LayoutOrder UsedAs<number> ❌ 0 Position in a parent UIListLayout or UIGridLayout.
Size UsedAs<UDim2> ❌ - Size of the component.
Visible UsedAs<boolean> ❌ true Whether the component is shown.
ZIndex UsedAs<number> ❌ - Z index of the component.
Children any ❌ - Content of the area. It is stacked in a list, unless ContentLayout is "None".
Orientation "Vertical" \| "Horizontal" ❌ "Vertical" Direction of scrolling.
ScrollBarThickness number ❌ 8 Width of the scroll bar thumb in pixels.
ScrollBarColor Color3 ❌ Colors.Outline Colour of the thumb.
ScrollBarActiveColor Color3 ❌ Colors.Primary Colour of the thumb while it is dragged.
ScrollBarRailThickness number ❌ 2 Width of the thin line the thumb moves along, in pixels.
ScrollBarRailBackground boolean ❌ true Draw the line the thumb moves along.
ScrollBarRailColor Color3 ❌ Colors.OutlineVariant Colour of that line.
ScrollBarPadding number ❌ 6 Space between the scroll bar and the edge of the area, in pixels.
Smooth boolean ❌ true Animate wheel scrolling instead of jumping.
Inertia boolean ❌ true Keep scrolling for a moment after a flick.
Keyboard boolean ❌ true Scroll with the arrow keys, Page Up, Page Down, Home and End.
AutoCanvas boolean ❌ true Size the scrollable area to the content.
CanvasSize UsedAs<UDim2> ❌ - Size of the scrollable area. Use it when AutoCanvas is false.
ScrollBarRail boolean ❌ true Pressing the line the thumb moves along jumps there.
AutoHideScrollBar boolean ❌ true Fade the scroll bar out when it is not in use.
AutoHideDelay number ❌ 0.85 Time in seconds before the scroll bar fades out.
ScrollButtons boolean ❌ false Show buttons at the ends of the scroll bar.
ScrollButtonStep number ❌ 64 Distance in pixels one press of a scroll button scrolls.
ScrollOffset UsedAs<number> ❌ 0 Scroll position in pixels. Pass a Value to also scroll from code.
Overscroll boolean ❌ true when Inertia Let the content stretch past its edges and spring back. When left out it is on if Inertia is on or OnRefresh is set.
RefreshThreshold number ❌ 72 How far in pixels the user must pull for OnRefresh to run.
PullIndicator boolean ❌ true when OnRefresh is set Show the hint while pulling. On when OnRefresh is set.
Refreshing boolean \| State<boolean> ❌ True while refreshing. The content rests at the threshold with a spinner until it turns false.
RefreshingHint string ❌ "Refreshing…" Text beside the spinner while Refreshing.
PullHint string ❌ "Keep scrolling to continue" Hint shown while the pull is short of the threshold.
ReleaseHint string ❌ "Release to continue" Hint shown once the pull is past the threshold.
DragToScroll boolean ❌ touch, or mouse when OnRefresh is set Scroll by dragging anywhere in the area. On for touch. With a mouse it is on when OnRefresh is set.
ContentLayout "List" \| "None" ❌ "List" "List" stacks the children. "None" leaves them where you put them.
ContentPadding number ❌ Metrics.SpaceMd Padding around the content in pixels. Use 0 for virtual lists.
ListPadding number ❌ Metrics.SpaceLg Gap between children in pixels.

Callbacks

Name Description
OnScroll: (offset: number) -> () Runs with the scroll position in pixels when it changes.
OnRefresh: () -> () Runs when the user pulls past the top and lets go.
OnPullCancel: () -> () Runs when the user pulled but let go before reaching the threshold.

See also