
## How To Use Babylon 3D GUI

The Babylon.js 3D GUI library is an extension you can use to generate 3D interactive user interface.

The latest version can be found on our CDN at https://cdn.babylonjs.com/gui/babylon.gui.js.

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

And the source code is available on the main Babylon.js repo: https://github.com/BabylonJS/Babylon.js/tree/master/packages/dev/gui.

## Introduction

Babylon.GUI uses meshes to create an interactive user interface, which is fully integrated in your scene.

## GUI3DManager

To begin with 3D GUI, you need to instantiate a `GUI3DManager` which will be responsible for connecting all the controls together:

```javascript
const manager = new BABYLON.GUI.GUI3DManager(scene);
```

The manager only requires the scene to work on. Once instantiated, the manager will create a utility layer which is a specific child scene that will host all the meshes used to render the controls. This way, your main scene won't get populated by the utility meshes.

You can reach the utility layer with `manager.utilityLayer`.

Once you have a manager, you can start adding controls with `manager.addControl(control)`. All controls will be added to the `manager.rootContainer`.

Please also note that the following functions are available:

- `containsControl()`: Gets a boolean indicating if the given control is in the root child list.
- `removeControl()`: Removes a control from the root child list.

The manager also supports a scaling option, `manager.useRealisticScaling`, that scales all added controls to a size more comfortable for XR interactions. Alternatively, a custom scaling can be applied to all controls by setting the value of `manager.controlScaling`. Scaling effects done in these ways can be overridden by updating the control's scale normally. Setting either of these values will apply the change to all existing and future controls the manager owns.

## Containers

A container is used to organize controls in the scene. The base class for all containers is the `Container3D` class. The `manager.rootContainer` is a `Container3D` object.

All containers provide the following functions to handle controls:

- `addControl()`: Adds a control to the children of this container
- `containsControl()`: Gets a boolean indicating if the given control is in the root child list
- `removeControl()`: Removes a control from the root child list

By default, all containers will update their layout every time you add a new control to it. But you can optimize this behavior if you plan to add multiple controls in a row with `container.blockLayout = true`:

```javascript
panel.blockLayout = true;
for (let index = 0; index < 30; index++) {
  const button = new BABYLON.GUI.Button3D("click me");
  panel.addControl(button);
}
panel.blockLayout = false;
```

The `Container3D` class will do nothing regarding layout of its controls. You need to use one of its children to get a specialized layout mechanism.

All specialized containers must implement the following function to provide layout mechanism:

- `_arrangeChildren()`: This function will be called every time a new control is added. This is where children class can decide how to organize controls

### StackPanel

The `StackPanel` container can be used to stack items either horizontally or vertically:

```javascript
const panel = new BABYLON.GUI.StackPanel3D();
panel.isVertical = true;
```

The panel will automatically arrange its content every time you add a new control.

You can specify the distance between elements with `panel.margin = 0.02`.

See it in action here: <Playground id="#HJZBRG#0" title="3D GUI StackPanel" description="Simple example showing how to add a 3D GUI StackPanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI1.jpg"/>

### VolumeBasedPanel

VolumeBasedPanel are containers used to dispatch items on the surface of a volume (like sphere or cylinder).

The panels will automatically arrange its content every time you add a new control.

The panels can either be row or column first depending on which property you use:

```javascript
panel.columns = 5; // The panel will automatically compute the number of rows based on number of child controls
```

or

```javascript
panel.rows = 5; // The panel will automatically compute the number of columns based on number of child controls
```

By default a VolumeBasedPanel is set up with panel.columns = 10;

You can specify the distance between elements with `panel.margin = 0.02`.

You can also control how each cell is oriented:

| Value | Type                                                | Description                                                     |
| ----- | --------------------------------------------------- | --------------------------------------------------------------- |
| 0     | BABYLON.Container3D.UNSET_ORIENTATION               | Control rotation will remain unchanged                          |
| 1     | BABYLON.Container3D.FACEORIGIN_ORIENTATION          | Control will rotate to make it look at sphere central axis      |
| 2     | BABYLON.Container3D.FACEORIGINREVERSED_ORIENTATION  | Control will rotate to make it look back at sphere central axis |
| 3     | BABYLON.Container3D.FACEFORWARD_ORIENTATION         | Control will rotate to look at z axis (0, 0, 1)                 |
| 4     | BABYLON.Container3D.FACEFORWARDREVERSED_ORIENTATION | Control will rotate to look at negative z axis (0, 0, -1)       |

#### SpherePanel

The `SpherePanel` container can be used to dispatch items on the surface of a sphere:

```javascript
const panel = new BABYLON.GUI.SpherePanel();
panel.radius = 5;
```

The radius property is used to define the radius of the hosting sphere.

See it in action here: <Playground id="#HB4C01#9" title="3D GUI SpherePanel" description="Simple example showing how to add a 3D GUI SpherePanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI2.jpg"/>

![SpherePanel](/img/how_to/gui/SpherePanel.jpg)

#### CylinderPanel

The `CylinderPanel` container can be used to dispatch item on the surface of a cylinder:

```javascript
const panel = new BABYLON.GUI.CylinderPanel();
panel.radius = 5;
```

The radius property is used to define the radius of the hosting cylinder.

See it in action here: <Playground id="#HB4C01#8" title="3D GUI CylinderPanel" description="Simple example showing how to add a 3D GUI CylinderPanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI3.jpg"/>

![CylinderPanel](/img/how_to/gui/CylinderPanel.jpg)

#### PlanePanel

The `PlanePanel` container can be used to dispatch item on the surface of a plane:

```javascript
const panel = new BABYLON.GUI.PlanePanel();
```

See it in action here: <Playground id="#HB4C01#7" title="3D GUI PlanePanel" description="Simple example showing how to add a 3D GUI PlanePanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI4.jpg"/>

![PlanePanel](/img/how_to/gui/PlanePanel.jpg)

#### ScatterPanel

The `ScatterPanel` container can be used to dispatch items using a randomized planar mapping:

```javascript
const panel = new BABYLON.GUI.ScatterPanel();
panel.iterations = 100;
```

The iterations property is used to define the number of iteration to use to scatter the controls (100 by default)

![ScatterPanel](/img/how_to/gui/ScatterPanel.jpg)

See it in action here: <Playground id="#HB4C01#6" title="3D GUI ScatterPanel" description="Simple example showing how to add a 3D GUI ScatterPanel to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI5.jpg"/>

## Controls

All controls inherit from the `Control3D` class which provides a set of basic features:

- `position`: Gets or sets the control position in world space
- `scaling`: Gets or sets the control scaling in world space
- `parent`: Gets or sets the parent container
- `isVisible`: Gets or sets a boolean indicating if the control is visible
- `node`: Gets the transform node used by this control
- `mesh`: Gets the mesh used to render this control

You can attach a control to a mesh or transform node from your scene with:

```javascript
control.linkToTransformNode(anchor);
```

This way the control will always follow the linked node or mesh. Please note that in this case, the `position` and `scaling` properties are considered local to the new parent node or mesh.
When linking a control to a transform node, please make sure that the control was first added to a container or to the root manager.

Some observables are also available to help tracking control state:

- `onPointerEnterObservable`: An event triggered when pointer enters the control
- `onPointerOutObservable`: An event triggered when the pointer move out of the control
- `onPointerDownObservable`: An event triggered when the pointer taps the control
- `onPointerUpObservable`: An event triggered when pointer is up
- `onPointerClickObservable`: An event triggered when a control is clicked on (with a mouse)
- `onPointerMoveObservable`: An event triggered when the pointer move over the control

All controls can also be the target of [behaviors](/features/featuresDeepDive/behaviors) so they expose the associated properties and functions:

- `behaviors`: Gets the list of attached behaviors
- `addBehavior()`: Attach a behavior to the control
- `removeBehavior()`: Remove an attached behavior
- `getBehaviorByName()`: Gets an attached behavior by name

All controls can also define a callback when specific event is happening. These callbacks will be called to let the user defines an animation for the control. Here is the list of available callbacks:

- `pointerEnterAnimation`: Callback used to start pointer enter animation
- `pointerOutAnimation`: Callback used to start pointer out animation
- `pointerDownAnimation`: Callback used to start pointer down animation
- `pointerUpAnimation`: Callback used to start pointer up animation

All these callbacks are empty by default and will be implemented by specialized controls.

### Button3D

`Button3D` is a class used to create 3D buttons.

A button is a control with default animations for enter/out/down and up events.
It is based on a 2D GUI content.

You can specify the content through the `content` property and set it to any regular [2D GUI content](/features/featuresDeepDive/gui):

```javascript
const button = new BABYLON.GUI.Button3D("reset");

const text = new BABYLON.GUI.TextBlock();
text.text = "reset";
text.color = "white";
text.fontSize = 24;
button.content = text;
```

By default the `Button3D` control uses a 512x512 AdvancedDynamicTexture to render its content.
You can use the following properties to change the texture resolution:

- `contentResolution`: Gets or sets the texture resolution used to render content (512 by default)
- `contentScaleRatio`: Gets or sets the texture scale ratio used to render content (2 by default)

See it in action here: <Playground id="#2YZFA0#0" title="3D GUI Button3D Control" description="Simple example showing how to add a 3D GUI Button3D to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI6.jpg"/>

### MeshButton3D

This class is used to create an interactive object which will use a mesh coming from the current scene to render.

```javascript
const pushButton = new BABYLON.GUI.MeshButton3D(mesh, "pushButton");
```

Once created, you can use the new MeshButton3D to add animations:

```javascript
pushButton.pointerEnterAnimation = () => {
  mesh.material.albedoColor = hoverColor;
};
pushButton.pointerOutAnimation = () => {
  mesh.material.albedoColor = new BABYLON.Color3(0.5, 0.19, 0);
};
```

See it in action here: <Playground id="#8Y780Y#20" title="MeshButton3D Demo" description="Demo of the MeshButton3D control." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI8.jpg"/>

### HolographicButton

The `HolographicButton` is a specialized button that mimics the Mixed Reality Toolkit holographic button.

An `HolographicButton` can be defined with two properties:

- `text`: Gets or sets text for the button
- `imageUrl`: Gets or sets the image url for the button

![Babylon.GUI](/img/how_to/gui/MRTK_HolographicButton.jpg)

See it in action here: <Playground id="#2YZFA0#2" title="3D GUI HolographicButton Control" description="Simple example showing how to add a 3D GUI HolographicButton to your scene." image="/img/playgroundsAndNMEs/divingDeeperBabylon3DGUI7.jpg"/>

Please note that you can overwrite the default content but you need to do it after the call to addControl:

```javascript
const button = new BABYLON.GUI.HolographicButton("reset");
panel.addControl(button);

// Must be done AFTER addControl in order to overwrite the default content
const text1 = new BABYLON.GUI.TextBlock();
text1.text = "Reset";
text1.color = "Red";
text1.fontSize = 48;
button.content = text1;
```

### TouchHolographicButton

The `TouchHolographicButton` is a newer version `HolographicButton` that is more suited for Hololens 2 volume interactions.  
It has the same use as `HolographicButton`:

```javascript
const button = new BABYLON.GUI.TouchHolographicButton("reset");
panel.addControl(button);

// Must be done AFTER addControl in order to overwrite the default content
const text1 = new BABYLON.GUI.TextBlock();
text1.text = "Reset";
text1.color = "Red";
text1.fontSize = 48;
button.content = text1;
```

The main functional difference between the `TouchHolographicButton` and `HolographicButton` is that the `TouchHolographicButton` supports near interactions (such as touching the button directly with hand tracking).

### HolographicSlate

The `HolographicSlate` is used to display content. It can be dragged around, rotated and scaled. With 1 pointer you have to use the handles to rotate and scale the slate, with 2 pointers you can pinch and twist the title bar to rotate and scale.

The `HolographicSlate` hosts an `AdvancedDynamicTexture` to display content, simply set the `content` property to a `Control` or collection of `Control`s to adjust what is displayed. It also has an adjustable title bar at the top that can display a title by setting the `title` property.

The dimensions can be manually set at any time, but are also updated when the user adjusts the slate using the handles around the outside of the slate. The dimensions will never go below the minimum dimensions in either direction, but the minimum dimensions can be set separately. If using the slate handles to resize, the aspect ratio will be maintained even when trying to resize smaller than the minimum.

```javascript
// Create the 3D UI manager
const manager = new BABYLON.GUI.GUI3DManager(scene);

// Let's add a slate
const slate = new BABYLON.GUI.HolographicSlate("down");
slate.title = "Checkers";
slate.minDimensions = new BABYLON.Vector(5, 5);
slate.dimensions = new BABYLON.Vector2(10, 10);
slate.titleBarHeight = 1.5;
manager.addControl(slate);
// Must be done AFTER addControl in order to overwrite the default content
slate.content = new BABYLON.GUI.Image("checkers", "./textures/Checker_Albedo.png");
```

Content inside the slate can also be scrolled in X or Y directions. Use the `contentResolution` property to manipulate the resolution of the texture.

The slate natively provides 2 `TouchHolographicButton` on the top right, the leftmost enables the [FollowBehavior](/features/featuresDeepDive/behaviors/meshBehaviors#followbehavior) for the slate, and the rightmost destroys the slate.

<Playground id="#SYD2M2#10" title="HolographicSlate" description="Simple Holographic Slate example"/>

### Near Menu

The `NearMenu` is a small control that displays buttons close to the user. By default, it follows the user with [FollowBehavior](/features/featuresDeepDive/behaviors/meshBehaviors#followbehavior). It can be pinned in the world either by using the pin button, or whenever the user drags the backplate.

Below, an example of a horizontal 3-button near menu.

```javascript
// Create the 3D UI manager
const manager = new BABYLON.GUI.GUI3DManager(scene);

// Let's add a slate
const near = new BABYLON.GUI.NearMenu("near");
manager.addControl(near);

const button0 = new BABYLON.GUI.TouchHolographicButton("button0");
button0.imageUrl = "./textures/IconFollowMe.png";
button0.text = "Button 0";
near.addButton(button0);

const button1 = new BABYLON.GUI.TouchHolographicButton("button1");
button1.imageUrl = "./textures/IconClose.png";
button1.text = "Button 1";
near.addButton(button1);

const button2 = new BABYLON.GUI.TouchHolographicButton("button2");
button2.imageUrl = "./textures/IconFollowMe.png";
button2.text = "Button 2";
near.addButton(button2);
```

As `NearMenu` is a child class of `VolumeBasedPanel`, the direction of the layout can be changed by tweaking the parameters `rows` and `columns`.

For example, to make a near menu with `n` buttons vertical, use :

```javascript
near.rows = n;
```

### Hand Menu

The `HandMenu` is a `NearMenu` that uses the [HandConstraintBehavior](/features/featuresDeepDive/behaviors/meshBehaviors#handconstraintbehavior). It is useful for XR experiences to always have a 3D menu in hand range.

By default, the `HandMenu` positions itself on the outer side of the users left hand, and only activates when the user both has their palm facing them and is looking at (facing) their hand. These defaults can be changed by modifying the properties on the `HandConstraintBehavior` attached to the `HandMenu`.

### Custom controls

You can create your own custom control by inheriting from the `Control3D` class and implementing the following functions:

- `_createNode()`: Called on controls to create a transform node or a mesh to represent the control
- `_affectMaterial()`: Called on controls to prepare and affect a material if a mesh is used to represent the control



## What is MRTK for Babylon.js

MRTK stands for the Mixed Reality Toolkit, a set of features, controls, and components designed to ease and accelerate development for VR and AR applications.

There currently only exists documentation for MRTK's [Unity](https://docs.microsoft.com/en-us/windows/mixed-reality/mrtk-unity/) and [Unreal](https://docs.microsoft.com/en-us/windows/mixed-reality/develop/unreal/unreal-mrtk-introduction) implementations, and so when we talk about matching what MRTK offers, we are comparing to what these offer.

This page will go over each of the MRTK-relevant controls and features present in BabylonJS, showing how each can be used. Many of the controls can also be viewed on the [3D GUI page here](/features/featuresDeepDive/gui/gui3D), and if a section has a relevant page, that will also be linked.

## GUI Controls

The following BabylonJS controls have roots as MRTK features. As they extend the `Control3D` class, they all support the basic capabilities that `Control3D` objects have.

More on the `Control3D` class, and 3D GUI elements in general, can be found [here](/features/featuresDeepDive/gui/gui3D).

The following is an example that showcases several of the controls listed, including `TouchHolographicButtons` , `TouchMeshButtons`, and the `NearMenu`. This scene is designed for use in XR, and supports use of `WebXRNearInteraction`:
<Playground id="#24DLJ4#7" title="Near Interaction Button Scene Demo" description="Demo showcasing different Control3D objects with Near Interaction support."/>

#### Holographic Button

The `HolographicButton` class is the standard, familiar button that can be placed and pressed in a 3D environment. It is based off of the MRTK `ButtonHoloLens1`, and supports a title, image, and tooltip.

#### Touch Holographic Button

The `TouchHolographicButton` is akin to MRTK's `PressableButtonHoloLens2`. It supports everything that the `HolographicButton` supports, but has more depth to it, allowing for visual feedback as it is being interacted with. As part of this added depth, it now responds to near interactions by having the button surface depress as the user's hand/motion controller presses it.

#### Touch Mesh Button

While the `TouchMeshButton` doesn't have a direct representation within MRTK, it is a button that offers custom visuals and support for near interactions. This allows for any object to react to near interaction, if desired, which aligns with MRTK's experimental `Hand Physics Service`.

Aside from the customization of its visuals, this button behaves in the same way as the `TouchHolographicButton`.

#### Holographic Slate

The `HolographicSlate` is a flat panel that can float in a 3D environment, used to display 2D content in XR experiences.

It consists of a titlebar and content pane. The titlebar has room for a custom title, plus a follow button and close button. The follow button will toggle whether the slate follows the user around or not, and the close button will destroy the slate. The content pane hosts an `AdvancedDynamicTexture`, which is [explained in more detail here](/features/featuresDeepDive/gui/gui).

See it in action here:
<Playground id="#43YQHC#2" title="Slate Scene w/ Label" description="A showcase of different uses for HolographicSlates."/>

#### Near Menu

The `NearMenu` is a `HolographicMenu` with an attached `FollowBehavior` that tries to stay tethered a set distance from the user at all times.

It is a menu designed for use in XR experiences, and by default stays about half an arm's length away. It also rotates to try and stay in the user's field of view.

The `NearMenu` also has a pin button, that when pressed, will freeze the menu in space. The menu can also be grabbed around the edges to move it (it comes with an attached `SixDofDragBehavior`), at which point it becomes pinned in order to maintain its new position.

#### Hand Menu

The `HandMenu` is a `HolographicMenu` that is anchored to the user's hand using a `HandConstraintBehavior`.

Its default position lies on the outside of the user's left hand, such that when their palm is up, the menu is facing them and easily accessible by their right hand.

The menu can be customized to appear by default on the right hand or either hand, and can also be anchored to a different quadrant of the hand. Only one menu will be visible at a time though, even if both hands are up. More information on this can be found in the `HandConstraintBehavior`'s section [here](/features/featuresDeepDive/gui/mrtk#hand-constraint-behavior).

#### Slider 3D

The `Slider3D` is a customizable slider with a 3D presence. The default range of the slider is from `0` to `1`, though that can be customized, along with the step count and precision.

The `Slider3D` can be created with a backplate, which is determined on creation. After creation, the `minimum` and `maximum` values can be adjusted, as well as the `step` size.

See it in action here:
<Playground id="#2PKNJB#7" title="Slider Color Changer" description="A basic example showing how 3D sliders can affect their surroundings."/>

## Behaviors and Gizmos

Some behaviors and Gizmos are also shared with MRTK components. In MRTK terminology, these are usually referred to as Solvers, Bounds Control, or Object Manipulators. Behaviors and Gizmos are attached to `Nodes`, `TransformNodes`, and `Meshes` in order to provide additional functionality.

More information on `Gizmos` can be found [here](/features/featuresDeepDive/mesh/gizmo), while behaviors are covered in more detail [here](/features/featuresDeepDive/behaviors/meshBehaviors).

#### SixDof Drag Behavior

The `SixDofDragBehavior`, also known as MRTK's `Object Manipulator` component. By creating and attaching it to an object in the scene, users are able to grab, move, and rotate the object. Interacting with a ray-cast input allows the object to be moved in 3-dimensions, while interacting with near interaction adds the ability to rotate the object in-place.

```javascript
const sixDofDragBehavior = new BABYLON.SixDofDragBehavior();
```

To attach a `SixDofDragBehavior` to a mesh in the scene, simply call the mesh's `addBehavior` function:

```javascript
mesh.addBehavior(sixDofDragBehavior);
```

#### Follow Behavior

The `FollowBehavior` tries to maintain a set distance between the `TransformNode` it's attached to, and the `followedCamera` target (defaults to main camera).

There are many aspects to this behavior that can be customized. These are the core properties:

| Property            | Type   | Description                                                                                        |
| ------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| followedCamera      | Camera | The camera the behavior will try to follow                                                         |
| defaultDistance     | float  | The starting distance to the camera, in meters                                                     |
| minimumDistance     | float  | The minimum distance before the behavior starts to move the attached `TransformNode` further away  |
| maximumDistance     | float  | The maximum distance before the behavior starts to move the attached `TransformNode` closer        |
| verticalMaxDistance | float  | The maximum height offset allowed between the camera's position and the `TransformNode`'s position |

#### Hand Constraint Behavior

The `HandConstraintBehavior` is a behavior that constrains the attached mesh to a specific location on the user's hand. The visibility of the attached mesh can be toggled based on the rotation of the hand and how centered it is in the user's field of view, by setting the `handConstraintVisibility` property.

This behavior takes advantage of the `WebXREyeTracking` feature, allowing the `handConstraintVisibility` propery to check whether the user is actively looking at their hand/the mesh or not. As a fallback if no eye data is available, it uses the direction the device is facing instead.

The following are the core properties that can be set to customize the behavior:

| Property            | Type                      | Description                                                                                                                                          |
| ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| targetZone          | HandConstraintSide        | An enum that determines which side/quadrant of the hand the mesh is anchored to and offset from                                                      |
| zoneOrientationMode | HandConstraintOrientation | Determines whether the attached mesh's position should rotate with the hand                                                                          |
| nodeOrientationMode | HandConstraintOrientation | Determines whether the attached mesh should rotate with the hand                                                                                     |
| handedness          | XRHandedness              | Should the attached mesh only stick to the left hand, or right hand? Defaults to none, allowing it to stick to either hand as they become available. |

#### Bounding Box Gizmo

The `BoundingBoxGizmo` is also known as MRTK's `Bounds Control` component. This creates small objects that surround the attached mesh, which can be interacted with to rotate, scale, and [translate](/typedoc/classes/babylon.transformnode#translate) the attached mesh.

## Background Features

These are features that work in the background to enhance the capabilities available to a user.

General XR features are covered in detail [here](/features/featuresDeepDive/webXR/WebXRSelectedFeatures), while AR-specific features are covered in detail [here](/features/featuresDeepDive/webXR/webXRARFeatures).

#### Hand Tracking and Near Interaction

The Hand Tracking feature, `WebXRHandTracking`, is an enhancement to hand inputs for XR devices that support it.

This feature provides articulated joint tracking, hand meshes, and enables the use of touch interactions using near interaction.

The `WebXRNearInteraction` feature is enabled by default on the Babylon playground, and allows for touch interactions when using hands or motion controllers. Touch-supported objects will be able to dynamically react to 3D input, creating a more immersive experience than what basic buttons can provide.

If the `WebXRHandTracking` feature is not enabled, then the near interaction model used will be a visible orb that floats in front of the hand (or motion controller). This orb will only be visible while near a component that supports Near Interaction.

To provide support for Near Interaction to an arbitrary `AbstractMesh`, simply set the `isNearPickable` and/or `isNearGrabbable` properties. `isNearPickable` will enable near interaction in the form of touch input, whereas `isNearGrabbable` will allow the object to be grabbed. The main difference here is that touch input triggers a press on touch, but grabbing the object requires touch _and_ a trigger of some kind (pulling the trigger on a controller, or performing a pinch gesture with a hand). At most one of these options should be enabled for a given object at any given time, to prevent unintended interactions.

#### Eye Tracking

Disclaimer: The Eye tracking feature is only supported with BabylonNative for now.

The Eye Tracking feature, `WebXREyeTracking`, is an opt-in feature for supported XR devices that captures the direction the user's eyes are facing, and passes that along for developers to use.

To use, simply enable the Eye Tracking feature when setting up a project in BabylonNative.

You then have the option to either listen to an observable, or directly query the component for the latest data. Eye tracking data is always provided as a `Ray`.



## The Selection Panel Helper

A `SelectionPanel` contains groups of checkboxes, radio buttons and sliders. Though not as versatile as building your own interface with your own custom arrangement of controls it can be a quick way to construct a method of changing scene parameters for objects within your scene.

![selection panel](/img/GUI/selectPanel1.jpg)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fig 1

## Referencing a Selection Panel

As you can see in **Fig 1** a selection panel rectangle contains a vertical organization of groups numbered from the top starting at 0. Each group contains a header and a variable number of selectors. Each selector consists of a (or button) and a label. Within any one group all the selectors must be of the same type. You can refer to a selector by its group number and then the position of the selector within the group. So the checkbox labelled _High_ has reference 0, 1, ie. group 0, selector 1.

**NOTE** Adding or removing groups or selectors with change the reference number. The reference number always refers to the current positioning of the group and of the selector.

## Creating a Selection Panel

As usual with GUI containers you will need to create an advanced dynamic texture to add the selection panel to. You can set the dimensions and position of the selection panel. The format to construct a blank selection panel is

```javascript
new BABYLON.GUI.SelectionPanel(name);
```

After construction you can add groups of selectors, each newly added group is placed below any already added groups. For example

```javascript
const advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");

const selectBox = new BABYLON.GUI.SelectionPanel("selectBox");
selectBox.width = 0.25;
selectBox.height = 0.52;
selectBox.horizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;
selectBox.verticalAlignment = BABYLON.GUI.Control.VERTICAL_ALIGNMENT_BOTTOM;

advancedTexture.addControl(selectBox);

selectBox.addGroup(rotateGroup);
selectBox.addGroup(transformGroup);
selectBox.addGroup(colorGroup);
```

- <Playground id="#9M6M2I" title="Selection Panel with Added Groups" description="Simple example showing how to add a selection panel with added groups to your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector1.jpg"/>

In addition if you have already constructed selector groups then you can then pass them in an array when you create the selection panel. The format for this is

```javascript
new BABYLON.GUI.SelectionPanel(name, [selector groups])
```

Example

```javascript
const advancedTexture = BABYLON.GUI.AdvancedDynamicTexture.CreateFullscreenUI("UI");

const selectBox = new BABYLON.GUI.SelectionPanel("selectBox", [transformGroup, colorGroup, rotateGroup]);
selectBox.width = 0.25;
selectBox.height = 0.52;
selectBox.horizontalAlignment = BABYLON.GUI.Control.HORIZONTAL_ALIGNMENT_LEFT;
selectBox.verticalAlignment = BABYLON.GUI.Control.VERTICAL_ALIGNMENT_BOTTOM;

advancedTexture.addControl(selectBox);
```

- <Playground id="#BXMTCD" title="Selection Panel and Groups on Creation" description="Simple example showing how to add a selection panel with added groups on creation." image="/img/playgroundsAndNMEs/divingDeeperSelector1.jpg"/>
- <Playground id="#BXMTCD#1" title="Selection Panel with Both Approaches" description="Simple example showing how to add a selection panel with both approaches." image="/img/playgroundsAndNMEs/divingDeeperSelector1.jpg"/>

## Creating Groups

There are three types of groups, a checkbox group, a radio group and a slider group, which are created using the structure

```javascript
new BABYLON.GUI.<Type>Group(header)
```

For example

```javascript
const transformGroup = new BABYLON.GUI.CheckboxGroup("Transformation");
const colorGroup = new BABYLON.GUI.RadioGroup("Color");
const rotateGroup = new BABYLON.GUI.SliderGroup("Rotation");
```

## Creating Selectors

Naturally there are three types of selectors and each can only be added to the appropriate group. External functions for each selector refer any changes in the value to properties of scene objects.

Checkbox and radio selectors are simply added to their group using two parameters, a label name and the external function reference. An optional third parameter can set the initial checked state of the selector to true (default value is false).

A slider selector is added to its group with a number of parameters, the first two being as before a label name and a reference to the external function. Due to the nature of a slider the following optional parameters can be set

| Parameter     | Description                                              | Default |
| ------------- | -------------------------------------------------------- | ------- |
| unit          | a string describing the units used, eg degrees or metres | "Unit"  |
| min           | the minimum value for the slider                         | 0       |
| max           | the maximum value for the slider                         | 100     |
| value         | the start value for the Slider between min and max       | 0       |
| onValueChange | the function used to format the value displayed          | void    |

New selectors are added below those already added.

Example usage

```javascript
transformGroup.addCheckbox("Small", toSize);
transformGroup.addCheckbox("High", toPlace);

colorGroup.addRadio("Blue", setColor, true);
colorGroup.addRadio("Red", setColor);

rotateGroup.addSlider("Angle Y", orientateY, "degs", 0, 2 * Math.PI, 0, displayValue);
rotateGroup.addSlider("Angle X", orientateX, "degs", 0, 2 * Math.PI, Math.PI, displayValue);
```

## Selector Called Functions

### Checkbox Selector

One function for each selector. Each requires a Boolean parameter with actions depending whether the control is checked or not

Examples

```javascript
const toSize = function (isChecked) {
  if (isChecked) {
    box.scaling = new BABYLON.Vector3(0.5, 0.5, 0.5);
  } else {
    box.scaling = new BABYLON.Vector3(1, 1, 1);
  }
};

const toPlace = function (isChecked) {
  if (isChecked) {
    box.position.y = 1.5;
  } else {
    box.position.y = 0.5;
  }
};
```

### Radio Selector

Within a radio group the same function is used for all selectors. The function requires a number parameter which will match the selector position with actions for each selector

Examples

```javascript
const setColor = function (but) {
  switch (but) {
    case 0:
      box.material = blueMat;
      break;
    case 1:
      box.material = redMat;
      break;
  }
};
```

### Slider Selector

Each slider selector requires two functions, one to change scene object properties and one to set the display format within the slider label.

Examples

```javascript
// Change mesh
const orientateY = function (angle) {
  box.rotation.y = angle;
};

const orientateX = function (angle) {
  box.rotation.x = angle;
};

//Format value
const displayValue = function (value) {
  return BABYLON.Tools.ToDegrees(value) | 0;
};
```

## Customize the Selection Panel

### Colors and Font

For consistency of appearance you can only change the overall font and color of all headers, all labels and all selector buttons.

- <Playground id="#BXMTCD#4" title="Selection Panel with Font Change" description="Simple example showing how to add a selection panel with a font change." image="/img/playgroundsAndNMEs/divingDeeperSelector2.jpg"/>

Without any direct setting, the color of labels follows that of the selection panel.

It is possible to set the color of all headers, labels, separator bars and selector buttons and the background color of all selector buttons.

```javascript
selectBox.color = "blue";
selectBox.background = "#FFFF99";
selectBox.barColor = "#4F7DF2";
selectBox.headerColor = "blue";
selectBox.buttonColor = "orange";
selectBox.buttonBackground = "#684502";
selectBox.labelColor = "brown";
```

- <Playground id="#BXMTCD#2" title="Selection Panel with Color Changes no labels" description="Simple example showing how to add a selection panel with color changes apart from labels." image="/img/playgroundsAndNMEs/divingDeeperSelector3.jpg"/>
- <Playground id="#BXMTCD#3" title="Selection Panel with Color Changes" description="Simple example showing how to add a selection panel with a color change." image="/img/playgroundsAndNMEs/divingDeeperSelector4.jpg"/>

Individual headers and labels can have their text changed.

```javascript
selectBox.setHeaderName("Move", 0);
selectBox.relabel("Theta", 2, 0);
```

- <Playground id="#BXMTCD#5" title="Selection Panel Change Group Header" description="Simple example showing how to add a selection panel and change the group header." image="/img/playgroundsAndNMEs/divingDeeperSelector5.jpg"/>
- <Playground id="#BXMTCD#6" title="Selection Panel Change Selector Label" description="Simple example showing how to add a selection panel and change the selector label." image="/img/playgroundsAndNMEs/divingDeeperSelector5.jpg"/>

### Groups and Selectors

As stated earlier you can add groups at the bottom of the selection panel at any time. You can also remove a group by reference to its position in the list, eg

```javascript
selectBox.removeGroup(2);
```

**Note** Groups below the removed group will have new positions and so need to be referenced by their new position.

In the same way a selector of the correct type can be added to the bottom of a group at any time using the `add<Type>` method.

```javascript
transformGroup.addCheckbox("Across", toLeft);
```

- <Playground id="#BXMTCD#7" title="Selector Group Add Selector" description="Simple example showing how to add a selector group and add a selector to your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector6.jpg"/>

A selector can be removed from a group at any time using its position in the group, eg

```javascript
transformGroup.removeSelector(1);
colorGroup.removeSelector(0);
rotationGroup.removeSelector(0);
```

- <Playground id="#BXMTCD#8" title="Selector Group Add Selector" description="Simple example showing how to add a selector group and remove a selector from your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector6.jpg"/>

For a selector within a group that is contained within a selection panel you can add a selector by use of the group position and correct parameters, eg

```javascript
selectBox.addToGroupSlider(2, "Angle X", orientateX, "degs", 0, 2 * Math.PI, Math.PI, displayValue);
```

- <Playground id="#BXMTCD#9" title="Selector Panel Add Selector" description="Simple example showing how to add a selector panel and add a selector to your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector6.jpg"/>

and remove a selector by using its reference position, ie. group and selector position in the group. For example

```javascript
selectBox.removeFromGroupSelector(0, 0);
```

- <Playground id="#BXMTCD#10" title="Selector Group Remove Selector" description="Simple example showing how to add a selector group and remove a selector from your scene." image="/img/playgroundsAndNMEs/divingDeeperSelector6.jpg"/>
