
# The Scroll Viewer

When you want to keep your user interface small and the information to present large you can use the **ScrollViewer** to contain the information.

![ScrollViewer](/img/GUI/scroll1.jpg).

It consists of vertical and horizontal scroll bars and a viewing area. The information you want to present is created as a control that you add to your scroll viewer and is shown in the viewing area. If all the information control fits inside the scroll viewer no scroll bars will be shown.

From Babylon.js version 4.1 onwards it is possible to use an image for the thumb control and in the bars

![ScrollViewer with Image Bars](/img/GUI/scroll4.jpg).

## Creating the Scroll Viewer

The scroll viewer base is a rectangle container holding the scroll bars and the viewing area. You create it with or without a name.

```javascript
const myScrollViewer = new BABYLON.GUI.ScrollViewer();
// OR
const myScrollViewer = new BABYLON.GUI.ScrollViewer("name");
```

and add it to an advanced texture as usual.

```javascript
const myAdvancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");
myAdvancedTexture.addControl(myScrollViewer);
```

You can then create your control or container of controls to add to the scroll viewer using the **addControl** method.

```javascript
myScrollViewer.addControl(myControl);
```

- <Playground id="#13CF95#1" title="Scroll Viewer Example" description="Simple example showing how to add a Scroll Viewer to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer1.jpg"/>

The default setting for width and depth of the scroll viewer is 100% of the parent control.

The following table shows the additional properties of a scroll viewer.

| Property      | Type   | Default     | Comments                                                     |
| ------------- | ------ | ----------- | ------------------------------------------------------------ |
| barColor      | string | grey        | Foreground color of the scroll bar and color of the thumb    |
| barBackground | string | transparent | Background color of the scroll bar and bottom right square   |
| thumbLength   | number | 0.5         | Proportion of thumb compared to scroll bar length (0 to 0.9) |
| barSize       | number | 20          | Height of scroll bar                                         |

**NOTE** All the padding values for the scroll viewer are set as 0. Any padding should be set on the control added to the scroll viewer.

- <Playground id="#C3RDBS#3" title="Scroll Viewer of Fixed Size" description="Simple example showing how to add a Scroll Viewer of fixed size to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer2.jpg"/>
- <Playground id="#C3RDBS#2" title="Scroll Viewer of Relative Size" description="Simple example showing how to add a Scroll Viewer of relative size to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer3.jpg"/>

## Scrollbars

Both scrollbars can be reached with:

- horizontalBar
- verticalBar

You can then set the scrollbar position with `scrollViewer.horizontalBar.value`. This value must be between 0 and 1.

## Image Scrollbars

In order to have images in the scroll bar you need to pass a name (can be empty string) and a parameter of true when creating the scroll viewer.

```javascript
const myScrollViewer = new BABYLON.GUI.ScrollViewer("", true);
```

Additional properties are available

| Property                                                   | Type      | Default | Comments                                                                                                         |
| ---------------------------------------------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| thumbImage<br/>horizontalThumbImage<br/>verticalThumbImage | GUI Image | none    | Image used for the thumb; required for image scroll bars                                                         |
| barImage<br/>horizontalBarImage<br/>verticalBarImage       | GUI Image | none    | Image for the scroll bars                                                                                        |
| thumbHeight                                                | number    | 1       | Proportion of thumb compared to bar height (0 to 1)                                                              |
| barImageHeight                                             | number    | 1       | Proportion of barImage compared to bar height (0 to 1)                                                           |
| scrollBackground                                           | string    | grey    | background color of scroll bars excluding the bottom right square; useful behind a thin or transparent bar image |

You do not have to have a barImage.

The images for the vertical bar and thumb are by default rotated copies of those used for the horizontal bar and thumb. You may want to keep the image sizes small if memory is an issue in your project.

You can also choose to have different images for the vertical and horizontal bar / thumb. In that case, use `horizontalThumbImage` / `verticalThumbImage` instead of `thumbImage` and `horizontalBarImage` / `verticalBarImage` instead of `barImage`.

- <Playground id="#4ZC0G4#2" title="Image Scroll Bars" description="Simple example showing how to add Image Scroll Bars to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer4.jpg"/>
- <Playground id="#4ZC0G4#1" title="Image Scroll Bars in a Grid" description="Simple example showing how to add Image Scroll Bars in a grid to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer5.jpg"/>

## Adding an Adjustable TextBlock Window

When you add a TextBlock of a given size to a scroll viewer both horizontal and vertical scroll bars are shown as needed.

![Contained TextBlock](/img/GUI/scroll3.jpg)

- <Playground id="#FX6KVK#3" title="Scroll Viewer with Fixed TextBlock" description="Simple example showing how to add a Scroll Viewer with Fixed TextBlock to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer6.jpg"/>

However quite often you need to present text fitting the width of the viewing window and scrolling for the height. This is achieved by setting the `textWrapping` and `reSizeToFit` as follows

```javascript
myTextBlock.textWrapping = BABYLON.GUI.TextWrapping.WordWrap;
myTextBlock.resizeToFit = true;
```

![Adjusting TextBlock](/img/GUI/scroll2.jpg)

- <Playground id="#3EF49E#5" title="Scroll Viewer with Adjusting TextBlock" description="Simple example showing how to add a Scroll Viewer with Adjusting TextBlock to your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer7.jpg"/>

## Live-Updating and Child Containers

The ScrollViewer accepts only ONE child control. If that single child is a textBlock, then you can modify its _.text_ property (including \\n linebreaks), to add/remove text content to/from that single textBlock.

The ScrollViewer also accepts a single CONTAINER (such as a stackpanel) for its single child. In that container, you may add/remove any type of control(s). For certain types of containers, you might choose to add `container.ignoreLayoutWarnings = true;`, and you might need to set a non-percentage _height_ value to certain children within the container(s).

## Rendering optimization

If you have a lot of controls in your scroll viewer window, you may notice a slow down in the rendering time.

To help improving your fps, you can set `myScrollViewer.freezeControls = true`. This will "freeze" the controls in their current position (in the window) and will make their rendering faster when the window is scrolled. When controls are frozen, a change in their position/size may not work, so if you must do it, first set `freezeControls` to `false`, do your changes then revert `freezeControls` back to `true`.

You can further improve the rendering time by using the `setBucketSizes` method:

```javascript
myScrollViewer.setBucketSizes(100, 40);
```

When `freezeControls` is true, setting a non-zero bucket size will improve performances by updating only controls that are visible. The bucket sizes is used to subdivide (internally) the window area to smaller areas into which controls are dispatched. So, the size should be roughly equals to the average size of all the controls inside the window. To disable the usage of buckets, sets either width or height (or both) to 0.

Please note that using this option will raise the memory usage (the higher the bucket sizes, the less memory used), that's why it is not enabled by default.

You can also use the `ScrollViewer.forceHorizontalBar` and `ScrollViewer.forceVerticalBar` properties.

When set to true, they force the display of the corresponding bars. When you know your scroll viewer will end up with visible bars, you can set those properties to true to save some initialization time, as if it is the scroll viewer control that makes a bar visible in the course of the initialization, it will trigger a children layout rebuild, adding more time to the initialization process.

<Playground id="#KPLW9F" title="Rendering Optimization" description="Simple example showing how to optimize rendering in your scene." image="/img/playgroundsAndNMEs/divingdeeperScrollViewer8.jpg"/>



## Graphical User Interface

There are a number of options for adding a GUI to Babylon.js. The [**Babylon GUI**](/features/featuresDeepDive/gui/gui) is covered in this section.

It allows you to place buttons and labels within in 3D space as well as a 2D front of screen GUI.
When you want a GUI that works in VR or within the 3D space it's the only option.

It is integrated within the playground. For your own projects it has to be loaded as well as Babylon.js.

<Playground id="#NGS9AU" title="Simple GUI Slider Example" description="Simple example of adding a GUI slider to your scene." image="/img/playgroundsAndNMEs/divingDeeperGUI1.jpg"/>

----------

Other possible GUIs are:

1. CastorGUI, a Babylon.js community extension which overlays the scene
1. Dat.GUI, an external interface
1. HTML GUI
1. HtmlMesh, a Babylon.js addon which allows HTML content to be included in the scene as a scene mesh or an overlay.

## CastorGUI

An alternative 2D GUI is the extension [CastorGUI](/communityExtensions/castorGUI). It has to be loaded both for the playground and for your own projects.

It can be found on [Github](https://github.com/dad72/CastorGUI).

<Playground id="#S34THY#14" title="CastorGUI Example" description="Simple example of using the CastorGUI system in your scene." image="/img/playgroundsAndNMEs/divingDeeperGUI2.jpg"/>

## Dat.GUI

The external [dat.GUI](https://github.com/dataarts/dat.gui) is integrated within the playground. For your own projects it has to be loaded as well as Babylon.js.

<Playground id="#NGS9AU#1" title="dat.GUI Example" description="Simple example of using the dat.GUI system in your scene." image="/img/playgroundsAndNMEs/divingDeeperGUI3.jpg"/>

## HTML GUI

Since Babylon.js is in JavaScript it is possible to use HTML and CSS to overlay the Babylon.js scene.

<Playground id="#1AHPN5" title="HTML GUI Example" description="Simple example of using HTML GUI elements in your scene." image="/img/playgroundsAndNMEs/divingDeeperGUI4.jpg"/>

### HtmlMesh

The [HtmlMesh](/addons/htmlMesh) extension for BabylonJS allows for HTML content to be incorporated into a scene either as a scene mesh that can occlude and be occluded by other meshes or as an overlay (similar to the HTML GUI example above, but using a mesh so it can be positioned using stadard transforms, parented to other meshes, dragged, and scaled using gizmos, etc...).

<Playground id="#HVHYJC#5" title="HtmlMesh Example" description="Example of using HtmlMesh elements in your scene." image="/img/playgroundsAndNMEs/htmlMeshPG.png"/>

## Comparison of GUI Options

Here's a list of the pros and cons of using different types of GUIs. It’s worth noting that these options aren’t mutually exclusive - they can be used together, depending on requirements, for instance:

- Use a simple HTML GUI for initial rapid protoyping, before transitioning to Babylon 2D or 3D GUI
- Use an HTML GUI overlay for complex, dynamic, text-heavy info panels but Babylon 2D GUI for everything else

The sky’s the limit! Go forth and GUI in whatever way takes your fancy!

### HTML-based GUI

#### Pros

- Use familiar HTML, CSS and front-end frameworks like Bootstrap, Tailwind, React, Vue, Svelte & Angular etc
- Near unlimited flexibility & mobile responsiveness
- High performance (as rendered by native browser rather than 3D engine)
- Easier to make WCAG accessibility compliant

#### Cons

- Looser integration with 3D scene
- Can’t have GUI elements directly within 3D scene (e.g. applied to meshes)
- Can’t apply 3D post processing effects to overlaid HTML GUI elements
- Can’t be used for fullscreen/native VR

### UI with HtmlMesh

#### Pros

- Use familiar HTML, CSS and front-end frameworks like Bootstrap, Tailwind, React, Vue, Svelte & Angular etc
- Near unlimited flexibility & mobile responsiveness
- High performance (as rendered by native browser rather than 3D engine)
- Easier to make WCAG accessibility compliant

#### Cons

- Can’t be used in Native or WebXR
- Cannot receive events from iframed content (unless same origin)
- On iOS, pointer interaction with content requires clicking on content first
- Small text can be blurry at some camera angles/distances

### Babylon 2D GUI

#### Pros

- There’s now an awesome [GUI Editor](/toolsAndResources/guiEditor) to make interface creation easier!
- Tight integration with 3D scene
- Ability to optionally apply scene post processing effects to GUI as well
- Ability to apply/link GUI elements and meshes
- Some unique, useful capabilities like nine-patch stretching and sprite-sheet animation that aren’t available with a raw HTML GUI

#### Cons

- Less comprehensive/flexible than HTML GUI (but still more than enough for most requirements)
- Depending on advanced dynamic texture resolution, GUI may look a little blurry
- Possibly some performance considerations
- Can’t be used for fullscreen/native VR

### Babylon 3D GUI

#### Pros

- Supports fullscreen/native VR
- Tight integration with 3D scene
- Ability to optionally apply scene post processing effects to GUI as well

#### Cons

- Less comprehensive/flexible than both Babylon 2D GUI and HTML GUI
