Scrollviews

Unity has only ever partially supported scrolling in UI (as of 2022: even Unity's latest releases of UIToolkit still don't correctly scroll, both in the API and even in the UnityEditor itself), so that 'scrolling' in Unity UIs is a complex and tricky subject. However, FlexBuilder has a fully automated integration that removes most of the problems for you (currently not all, but most) and you should find it relatively easy to work with.

Features of Scrolling in FlexBuilder

If you create a scrollable area using either of the methods listed below, FlexBuilder will preconfigure it for you correctly, with the following behaviours:

  • A new RootFlexContainer is created for the scroll-area, giving you fine control over it
  • If you set the container to be 'ROW' or 'ROW-REVERSED' it will scroll left/right
  • If you set the container to be 'COLUMN' or 'COLUMN-REVERSED' it will scroll up/down
  • When you add extra content (FlexItems) to the container, the scroll area will automatically update the scrollbars, size, etc
  • When you add FlexItems to the end of the container (default in Unity) the scroll area will remain at same position instead of resetting to top or bottom

Quickstart: how to add a scrollable container

First you have to decide what will be the scrollable part, and where it will sit within your UI.

Typically you choose a bottom-most object in your UI - i.e. a FlexItem with no FlexContainer and no children - and then you add the scrollable area inside that. The parent FlexItem will use Flexbox to decide its size and shape IGNORING the scrollable content, and the scrollable area will calculate its own size and shape (and all its children's sizes) IGNORING the parent and the rest of the Flexbox layout.

Typical settings for the FlexItem are:

  • Expand/contract to fit the available space:
    • flexGrow: 1
    • flexShrink: 1

However, you can also insert the scrollable area directly into any piece of UnityUI (this is often how top-level flexbox layouts are configured) - the parent object can be any RectTransform.

Scrollable container via GUI/UnityEditor

This is the easiest way: right-click in the Hierarchy view on a FlexItem or RectTransform that you want to be the parent (see section above for info on choosing the parent), and select the option for a Flex ScrollRect or Scrollview:

This will auto create the objects, place them into the scene, and correctly pre-configure them.

Scrollable container via script/code

When creating UI from code, or programmatically, you sometimes need to insert a scrollable area from script. For these situations we have a public API call that does almost exactly the same as the UI approach above.

Warning

⚠ this cannot be 'exactly' the same, as the UI approach above has access to Editor-only APIs inside Unity that enable it to do more things automatically. The scripting API provided works both in Editor and at Runtime / Player builds, and when you add to the UI at runtime you are limited by mistakes in Unity's own architecture. The net result: you have to do a little bit of it manually (Unity specifically blocks us from doing this for you).

This is provided in a special class: <xref:NinjaTech.FlexBuilder.Helpers.ScrollviewHelper>

You can either manually use methods in that class to add and configure a Scrollview (including all its related info and necessary child objects), or you can use the extension methods that allow you to ignore the class and add items directly to any GameObject, e.g.:

GameObject myGO = ... var layoutAlgorithm = ... myGO.AddFlexContainerInScrollview( layoutAlgorithm );

Important

⚠ Note: you MUST provide an initial LayoutAlgorithm with these methods - unfortunately Unity blocks us from reading project-settings at runtime (all versions up to 2022), so we cannot automatically pick-up the default algorithm. It's up to you how you decide which instance of IFlexboxLayoutAlgorithm to provide to the method.

Limitations of FlexBuilder Scrollviews

Scrollviews can only scroll horizontally OR vertically

This will be fixed in a future version, but the vast majority of UIs only need to scroll in one direction at a time.

Bugs in Unity Scrollviews

If you want to manually build a ScrollRect / Scroller in Unity you will have to understand and workaround all the individual bugs in Unity itself. This is true both in UnityUI and in UIToolkit - Unity so far has failed to fix or completely implement scrolling in either system.

These bugs include (but are not limited to):

  • UnityUI scrollviews don't automatically detect new content and resize
  • UnityUI scrollviews incorrectly position the scrollbar when content changes
  • UnityUI scrolling has never fully worked in any version of Windows (they incorrectly read the mousewheel)
  • UIToolkit scrollviews only work in one direction
  • UIToolkit scrollviews measure the scrollable area incorrectly, causing some content to always be 'off screen'