iTwin Viewer

The iTwin Viewer is a configurable iTwin.js viewer that provides the ability to view and interact with iModels. It includes basic capabilities and can be extended with iTwin.js extensions. The iTwin Viewer includes several tools.

  • Selection tools to select, hide, and emphasize elements
  • Basic measurement tools
  • Basic clipping tools
  • Basic navigation tools to pan, zoom, and rotate
  • Walk tool and camera tool
  • Basic tree view and property grid
  • Status bar with tool-specific contextual information

Creating an app to view an iModel

You can use Create React App to quickly set up a single page React application to view an iModel. The iTwin Viewer Create React App Template provides a template for Create React App for applications which are based on the iTwin Viewer. The following steps can be used to develop and build the application.

Development prerequisites

First you need to install the required prerequisites. Writing an iTwin.js application requires Node.js (LTS version) which provides the backend JavaScript runtime. The installation also includes the npm command line tool.

Suggested tools

  • Visual Studio Code is the recommended editor and debugger for iTwin.js applications. VS Code also supplies a graphical user interface for working with Git.
  • Google Chrome is the preferred tool for developing and debugging frontend JavaScript.
  • The VS Code extension Debugger for Chrome can also be quite helpful.

Recommended reading

  • TypeScript

    iTwin.js applications are written in TypeScript and then compiled to plain JavaScript.

  • Node Package Manager (npm)

    npm is used to install and manage dependencies of an iTwin.js application. The npm command line and npm scripts are used to build and test iTwin.js applications.

Development steps

  1. Install the necessary prerequisites.

  2. From a terminal, npx create-react-app@latest your-app-name --template @itwin/web-viewer --scripts-version @bentley/react-scripts.

    This will generate a new application based on the iTwin Viewer React component in the your-app-name directory.

  3. Open the your-app-name directory in VS Code.

  4. Go to in a web browser.

  5. Click the Sign In button and sign-in using your Bentley account credentials

  • If you have not already registered, click Register now and complete the registration process.
  1. Click on your user icon and navigate to the My Apps page
  2. Click the Register New button
  3. Give your application a Name
  4. Select the Visualization API
  5. Select application type SPA (Single Page Web Application)
  6. Enter Redirect URL https://localhost:3000/signin-callback
  7. Leave post logout redirect URIs empty.
  8. Click the Save button
  9. Once your new application is saved and a clientId is generated, add the clientId, list of scopes, and redirect url to the following variables in the .env file within the application's root directory: IMJS_AUTH_CLIENT_CLIENT_ID, IMJS_AUTH_CLIENT_SCOPES,IMJS_AUTH_CLIENT_REDIRECT_URI.
  10. Add a valid projectId and iModelId for your user to the IMJS_ITWIN_ID and IMJS_IMODEL_ID variables in the same .env file. You can obtain the ids using the Projects and iModels REST APIs.
  11. From a terminal at your application's root directory, npm start. This will serve the application with live reloading.
  12. Add/Update/Remove files as needed for your use case. If running npm start while making changes, your application should re-compile and reload.
  13. The viewer can be modified via the Viewer component in the App.tsx file. Visit the iTwin Viewer React documentation for more information.
  14. Review the file in the root directory of your application for additional development information.


From a terminal at your application's root directory, npm run build. This will create a deployment-ready build in the "build" folder within the application's root directory. It is not necessary to build the application during development.


Extending the capabilities

The iTwin Viewer can be extended with iTwin.js extensions. An iTwin.js extension is a separate JavaScript module that can load on demand into an iTwin.js frontend application. The separate deliverable enables an extension to provide extensibility of an iTwin.js application at runtime.

Each extension is its own separate bundle that has access to all iTwin.js shared libraries to enable seamless integration with the host app. Extensions can be used to expand the behavior of iTwin Viewer to support your custom workflows. The iTwin.js SDK includes more information about creating iTwin.js extensions.