> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/development/api-reference/classes/scrollingframe.md). # ScrollingFrame ScrollingFrame : `GuiObject` ## Overview ScrollingFrame is a UI container that can be used to automatically provide horizontal or vertical scroll when UI element placed inside overflows display area. It is especially useful when many items such as inventory and quest list need to be neatly displayed on single screen. Many different scroll actions can be set depending on situation. ScrollingFrame can be controlled only in **client environment**. ## Properties ### AbsoluteCanvasSize `Vector2` A read-only property that defines the total size of area scrollable by user. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") wait(2) print(ScrollingFrame.AbsoluteCanvasSize) ``` ### AbsoluteWindowSize `Vector2` A read-only property that defines the actual size of display area not including scroll bar area. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") print(ScrollingFrame.AbsoluteWindowSize) ``` ### AutomaticCanvasSize `Enum.AutomaticSize` A property that can be used to automatically adjust CanvasSize depending on the actual size of the content inside ScrollingFrame. If AutomaticSize is not None, AbsoluteCanvasSize is calculated based on the actual size of internal UI elements according to a specified direction and updated automatically. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.AutomaticCanvasSize = Enum.AutomaticSize.XY ``` ### BottomImage `string` Specifies the Asset Id of the image to display at the bottom end of the scroll bar. Its value is synchronized with BottomImageContent. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.BottomImage = "ovdrassetid://1234" ``` ### BottomImageContent `Content` Specifies, in Content format, the image to display at the bottom end of the scroll bar. Its value is synchronized with BottomImage. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") print("BottomImageContent : ", ScrollingFrame.BottomImageContent) ``` ### CanvasPosition `Vector2` A property that can be used to specify the current position of canvas in ScrollingFrame in pixel. Scroll bar will be moved to an appropriate position according to set value. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.CanvasPosition = Vector2.new(0, 210) ``` ### CanvasSize `UDim2` Specifies the size of the entire area that user can move with scrolls. If scroll threshold needs to be automatically calculated according to the quantity of internal content, AutomaticCanvasSize can be used. In addition, if AutomaticCanvasSize is enabled while the CanvasSize value is specified manually and the manually specified CanvasSize value is greater than automatically calculated size, the manually specified value takes precedence of automatically calculated size. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.CanvasSize = UDim2.new(0, 0, 0, 400) ``` ### DraggingScrollBar `Enum.DraggingScrollBar` A read-only property that indicates the scroll bar currently being dragged. It is None when no scroll bar is being dragged. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") print("DraggingScrollBar : ", ScrollingFrame.DraggingScrollBar) ``` ### ElasticBehavior `Enum.ElasticBehavior` Specifies the condition for using the elastic effect, in which the content goes past the scroll boundary and springs back when dragged further at the boundary. * `WhenScrollable`: Used only when there is scrollable content. * `Always`: Always used. * `Never`: Not used. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.ElasticBehavior = Enum.ElasticBehavior.Never ``` ### HorizontalBarRect `Rect` A read-only property that represents, as a rectangle in pixels, the area the horizontal scroll bar occupies on screen. If the horizontal scroll bar is not displayed, it is a rectangle with a size of 0. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") print("HorizontalBarRect : ", ScrollingFrame.HorizontalBarRect) ``` ### HorizontalScrollBarInset `Enum.ScrollBarInset` Specifies the condition for applying the thickness of the horizontal scroll bar as an inset of the content area. * `None`: Does not apply the inset. * `ScrollBar`: Applies the inset only when the scroll bar is displayed. * `Always`: Always applies the inset. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.HorizontalScrollBarInset = Enum.ScrollBarInset.ScrollBar ``` ### MaxCanvasPosition `Vector2` A read-only property that indicates the maximum value that can be specified for CanvasPosition. For each axis, it is AbsoluteCanvasSize minus AbsoluteWindowSize, and it does not become less than 0. If a larger value is specified for CanvasPosition, it is limited to this value. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.CanvasPosition = Vector2.new(0, ScrollingFrame.MaxCanvasPosition.Y) -- Scroll to the bottom ``` ### MidImage `string` Specifies the Asset Id of the image to display in the middle part of the scroll bar. Its value is synchronized with MidImageContent. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.MidImage = "ovdrassetid://1234" ``` ### MidImageContent `Content` Specifies, in Content format, the image to display in the middle part of the scroll bar. Its value is synchronized with MidImage. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") print("MidImageContent : ", ScrollingFrame.MidImageContent) ``` ### ScrollBarImageColor3 `Color3` Specifies the color of scroll bar image. If this value is white, original image will be displayed without any color correction. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.ScrollBarImageColor3 = Color3.fromRGB(255, 0, 0) ``` ### ScrollBarImageTransparency `number` Specifies the transparency of scroll bar image. 0 means the image is completely opaque while 1 means the image is totally invisible. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.ScrollBarImageTransparency = 0.3 ``` ### ScrollBarThickness `number` Specifies the width of scroll bar in pixel. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.ScrollBarThickness = 30 ``` ### ScrollingDirection `Enum.ScrollingDirection` Specifies in which direction user can scroll content. Scroll bar is generated only for the selected direction. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.ScrollingDirection = Enum.ScrollingDirection.Y ``` ### ScrollingEnabled `boolean` Specifies whether to allow scroll action. If scroll is disabled, scroll bar is not displayed and user cannot scroll content. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.ScrollingEnabled = false ``` ### ScrollRate `number` Specifies the scale of the scroll amount. The default is 1, and values less than 0 are treated as 0. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.ScrollRate = 2 ``` ### ScrollVelocity `Vector2` A read-only property that indicates the current scroll velocity in pixels per second. The direction in which CanvasPosition increases is positive. It is the same as the return value of GetScrollVelocity(). #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") print("ScrollVelocity : ", ScrollingFrame.ScrollVelocity) ``` ### SmoothScroll `boolean` Specifies whether to keep scrolling smoothly with inertia even after the scroll input is released. The default is true. If set to false, any inertial scrolling in progress also stops immediately. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.SmoothScroll = false ``` ### TopImage `string` Specifies the Asset Id of the image to display at the top end of the scroll bar. Its value is synchronized with TopImageContent. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.TopImage = "ovdrassetid://1234" ``` ### TopImageContent `Content` Specifies, in Content format, the image to display at the top end of the scroll bar. Its value is synchronized with TopImage. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") print("TopImageContent : ", ScrollingFrame.TopImageContent) ``` ### VerticalBarRect `Rect` A read-only property that represents, as a rectangle in pixels, the area the vertical scroll bar occupies on screen. If the vertical scroll bar is not displayed, it is a rectangle with a size of 0. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") print("VerticalBarRect : ", ScrollingFrame.VerticalBarRect) ``` ### VerticalScrollBarInset `Enum.ScrollBarInset` Specifies the condition for applying the thickness of the vertical scroll bar as an inset of the content area. * `None`: Does not apply the inset. * `ScrollBar`: Applies the inset only when the scroll bar is displayed. * `Always`: Always applies the inset. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.VerticalScrollBarInset = Enum.ScrollBarInset.ScrollBar ``` ### VerticalScrollBarPosition `Enum.VerticalScrollBarPosition` Specifies where to display the vertical scroll bar. * `Left`: Displays it on the left. * `Right`: Displays it on the right. This is the default. #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame.VerticalScrollBarPosition = Enum.VerticalScrollBarPosition.Left ``` ## Methods ### ClearInertialScrolling A method that immediately stops inertial scrolling in progress. CanvasPosition stays at the position where it stopped. It behaves the same as ResetScrollVelocity(). #### Parameters #### Return | `void` | | | ------ | - | #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame:ClearInertialScrolling() ``` ### GetSampledInertialVelocity A method that returns the raw value of the inertial velocity measured from recent scroll input. Since scale and direction corrections are not applied to this value, using GetScrollVelocity() is recommended for checking the scroll velocity in general. #### Parameters #### Return | `Vector2` | The inertial velocity before correction. | | --------- | ---------------------------------------- | #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") local SampledInertialVelocity = ScrollingFrame:GetSampledInertialVelocity() print("SampledInertialVelocity : ", SampledInertialVelocity) ``` ### GetScrollVelocity A method that returns the current scroll velocity. #### Parameters #### Return | `Vector2` | The scroll velocity in pixels per second. The direction in which CanvasPosition increases is positive. | | --------- | ------------------------------------------------------------------------------------------------------ | #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") local ScrollVelocity = ScrollingFrame:GetScrollVelocity() print("ScrollVelocity : ", ScrollVelocity) ``` ### MoveToSlot A method that can be used to move scrolls so that the UI element in a specified slot index position comes inside the display area of ScrollingFrame. slotIndex is decided not by hierarchy order, but the sort (display) order on actual screen. #### Parameters | `number` SlotIndex | The index value that represents the display (sort) order of the slot to become the reference point for scroll movement. | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | #### Return | `void` | | | ------ | - | #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame:MoveToSlot(3) ``` ### ResetScrollVelocity A method that immediately stops inertial scrolling in progress. CanvasPosition stays at the position where it stopped. #### Parameters #### Return | `void` | | | ------ | - | #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame:ResetScrollVelocity() ``` ### ScrollToTop A method that moves the scroll position to the top. For a ScrollingFrame displayed in a ScreenGui, it sets the Y value of CanvasPosition to 0 and keeps the X value. #### Parameters #### Return | `void` | | | ------ | - | #### Code Samples ```lua local ScreenGui = script.Parent local ScrollingFrame = ScreenGui:WaitForChild("ScrollingFrame") ScrollingFrame:ScrollToTop() ``` ## Events ## See also