---
title: Viewer Widget
slug: viewer-3d/viewer-widget
docTags: 
createdAt: 2024-06-07T14:48:52.190Z
---

Use the Viewer Widget API to include the Viewer Widget in your 3D viewer instance. The widget is useful for basic embedded viewer functionality. For more advanced usage make use of the Viewer APIs.

# Installation

Follow the same installation steps when using [jQuery](docId:18q6QATEr8draKQLdYXsl) with the following changes to include the Viewer Widget in your project.

- In step 4, provide the `viewer-ui` option to include the Viewer Widget.

```javascript
bimsync.load(["viewer-ui"]);
```

- In step 6, after loading a model initialize the Viewer Widget by invoking the `viewerUI` method on the jQuery object for the `div` where the 3D viewer instance is attached.

```javascript
$("#viewer-3d")
  .viewer("loadModelsFromToken", tokenUrl3d)
  .then(() => {
    $("#viewer-3d").viewerUI();
  });
```

# Usage

```html
<html>
  <head>
    <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
    <script src="https://api.catenda.com/js/v1/viewer2d"></script>
    <script src="https://api.catenda.com/js/v1/viewer3d"></script>
    <style>
      #viewer-2d {
        height: 50%;
        width: 100%;
      }
      #viewer-3d {
        height: 50%;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="viewer-3d"></div>
    <div id="viewer-2d"></div>
    <script type="text/javascript">
      let loadedViewersCount = 0;
      bimsync.setOnViewer2dLoadCallback(onViewersLoaded);
      bimsync.setOnLoadCallback(onViewersLoaded);

      bimsync.loadViewer2d();
      bimsync.load(["viewer-ui"]);

      function onViewersLoaded() {
        if (++loadedViewersCount < 2) return;

        const projectId = "YOUR_CATENDA_PROJECT_ID";
        const token = "YOUR_3D_VIEWER_TOKEN";

        const tokenUrl2d = `https://api.catenda.com/v2/projects/${project}/viewer2d/geometry?token=${token}`;
        const tokenUrl3d = `https://api.catenda.com/v2/projects/${project}/viewer3d/data?token=${token}`;

        const viewer2dOptions = {
          hoverSpaces: false,
          showViewpoint: false,
          selectColor: "#ff0000"
        };
        const viewer3dOptions = {
          textRenderMode: "dom"
        };
        const widgetOptions = {
          enableContextMenu: true,
          enableKeyboard: true,
          enableJoystick: true,
          enableViewer2dIntegration: true,
          joystickHidden: false,
          joystickPosition: "middle-right",
          lockStoreyMode: true,
          showViewer2dStoreySelect: true,
          viewer2dId: "viewer-2d"
        };

        $("#viewer-2d").viewer2d();
        $("#viewer-2d")
          .viewer2d("loadUrlPromise", tokenUrl2d)
          .then(() => {
            const storeys = $("#viewer-2d").viewer2d("getStoreys");
            if (storeys.length > 0) {
              $("#viewer-2d").viewer2d("showStorey", storeys[1].id);
            }
          });

        $("#viewer-3d").viewer(viewer3dOptions);
        $("#viewer-3d")
          .viewer("loadModelsFromToken", tokenUrl3d)
          .then(() => {
            $("#viewer-3d").viewerUI(widgetOptions);
          });
      }
    </script>
  </body>
</html>
```

# Options

Adjust the default behavior of the Viewer Widget by providing an options object when creating a Viewer Widget instance.

## Properties

| Name                                 | Type    | Default           | Description                                 |
| ------------------------------------ | ------- | ----------------- | ------------------------------------------- |
| `enableContextMenu`                  | Boolean | `false`           | Enable context menu features                |
| `enableJoystick`                     | Boolean | `true`            | Enable joystick widget                      |
| `enableKeyboard`                     | Boolean | `false`           | Enable keyboard shortcuts and navigation    |
| `enableViewer2dIntegration`          | Boolean | `false`           | Enable Viewer2D integration                 |
| `joystickBorderOffset`               | String  | `'20px'`          | Joystick border offset                      |
| `joystickColor`                      | String  | `'blue'`          | Valid RGB value for color ofjoystick wdiget |
| `joystickHidden`                     | Boolean | `true`            | Hide joystick widget                        |
| `joystickPosition`                   | String  | `'bottom-center'` | Position of joystick widget                 |
| `joystickRotationClamp`              | Number  | `2`               | Joystick rotation clamp                     |
| `joystickSize`                       | Number  | `100`             | Size of joystick widget                     |
| `lockStoreyMode`                     | Boolean | `false`           | Lock storey mode                            |
| `showViewer2dLockedNavigationToggle` | Boolean | `false`           | Show Viewer2D locked navigation toggle      |
| `showViewer2dStoreySelect`           | Boolean | `false`           | Show Viewer2D storey select                 |
| `spacesVisible`                      | Boolean | `false`           | Show spaces                                 |
| `viewer2dId`                         | String  | `null`            | DOM element id of 2D Viewer instance        |
| `translations`                       | Object  | `{}`              | Translations for the Viewer Widget          |

**joystickPosition**

Valid values are:

- `'middle-left'`
- `'bottom-left'`
- `'bottom-center'`
- `'bottom-right'`
- `'middle-right'`

**translations**

Translations for the Viewer Widget.

| Name                   | Default                  | Description                      |
| ---------------------- | ------------------------ | -------------------------------- |
| `addClippingPlane`     | `Add clipping plane`     | Add a clipping plane             |
| `defaultBuildingName`  | `(unknown building)`     | Default building name            |
| `defaultModelName`     | `(unknown model)`        | Default model name               |
| `hide`                 | `Hide`                   | Hide selected models             |
| `hideOthers`           | `Hide others`            | Hide all models except selected  |
| `isolate`              | `Isolate`                | Isolate selected models          |
| `loading`              | `Loading...`             | Loading models                   |
| `lookAt`               | `Look at`                | Look at selected models          |
| `makeTranslucent`      | `Make translucent`       | Make selected models translucent |
| `noModelsLoaded`       | `No models loaded.`      | No models loaded                 |
| `removeClippingPlanes` | `Remove clipping planes` | Remove all clipping planes       |
| `sectionTopAndBottom`  | `Section top and bottom` | Section top and bottom           |
| `showAll`              | `Show all`               | Show all models                  |

# Methods

## hideJoyStick

Hides the joystick.

### Usage

```javascript
$("#viewer-3d").viewerUI("hideJoystick");
```

## joystickPosition

Sets the joystick position.

### Usage

```javascript
const position = "bottom-center";
$("#viewer-3d").viewerUI("joystickPosition", position);
```

### Parameters

**position**

Position of the joystick.

| **Type** | **Required** |
| -------- | ------------ |
| String   | Yes          |

Valid values are:

- `'middle-left'`
- `'bottom-left'`
- `'bottom-center'`
- `'bottom-right'`
- `'middle-right'`

## set2dLockedNavigationMode

Set the 2D locked navigation mode. When enabled, the cursor will be in the center of the 2D scene.

### Usage

```javascript
const isLocked = true;
$("#viewer-3d").viewerUI("set2dLockedNavigationMode", isLocked);
```

### Parameters

**isLocked**

Positions the cursor in the center of the 2D scene.

| **Type** | **Required** |
| -------- | ------------ |
| Boolean  | Yes          |

## set2dLockStoreyMode

Set the 2D lock storey mode. When disabled, the 2D viewer storey selection will follow the 3D viewer.

### Usage

```javascript
const isLocked = false;
$("#viewer-3d").viewerUI("set2dLockStoreyMode", isLocked);
```

### Parameters

**isLocked**

Is the 2D lock storey mode enabled.

| **Type** | **Required** |
| -------- | ------------ |
| Boolean  | Yes          |

## setSpaces

Set the space ids to be considered when `spacesVisible` option is `false`.

### Usage

```javascript
const spaceIds = ["space-1", "space-2"];
$("#viewer-3d").viewerUI("setSpaces", spaceIds);
```

### Parameters

**spaceIds**

List of spaceIds

| **Type**       | **Required** |
| -------------- | ------------ |
| Array\[String] | Yes          |

## setSpacesVisible

Set spaces visibility.

### Usage

```javascript
const areSpacesVisible = true;
$("#viewer-3d").viewerUI("setSpacesVisible", areSpacesVisible);
```

### Parameters

**areSpacesVisible**

Are spaces visible.

| **Type** | **Required** |
| -------- | ------------ |
| Boolean  | Yes          |

## showJoyStick

Displays the joystick if enabled.

### Usage

```javascript
$("#viewer-3d").viewerUI("showJoystick");
```

## updateJoystickOptions

Sets the joystick options.

### Usage

```javascript
const options = {
  joystickBorderOffset: "20px",
  joystickColor: "blue",
  joystickHidden: false,
  joystickPosition: "bottom-center",
  joystickRotationClamp: 0.5,
  joystickSize: 200
};
$("#viewer-3d").viewerUI("updateJoystickOptions", options);
```

### Parameters

**options**

Options for the joystick.

| **Type** | **Required** |
| -------- | ------------ |
| Object   | Yes          |

**Properties**

| Name                    | Type    | Description                                                |
| ----------------------- | ------- | ---------------------------------------------------------- |
| `joystickBorderOffset`  | String  | Margin from edge of viewport                               |
| `joystickColor`         | String  | Color of the joystick                                      |
| `joystickHidden`        | Boolean | Is the joystick hidden                                     |
| `joystickPosition`      | String  | Position of the joystick                                   |
| `joystickRotationClamp` | Number  | Speed of scene navigation, valid value between `0` and `1` |
| `joystickSize`          | Number  | Size of the joystick in pixels                             |

**joystickPosition**

Valid values are:

- `'middle-left'`
- `'bottom-left'`
- `'bottom-center'`
- `'bottom-right'`
- `'middle-right'`