News Examples Documentation Download Buy Forum Contact



XML Extensions


Third Party Software
for krpano

Embedding into HTML Version 1.21

For embedding the krpano viewer into a HTML page the krpano.js script file (the filename can differ) need to be included and the embedpano() function be called.

Script Including

The krpano script file need to be included once anywhere (but before the embedpano() usage) on the html page:
<script src="krpano.js"></script>

Some details and notes:
  • The 'krpano.js' file can be named different - e.g. when using the MAKE PANO or MAKE VTOUR droplets it's typically named 'pano.js' or 'tour.js'.
  • The file itself contains the krpano viewer and when registered also the license information.
  • Typically the file is always the same for all panos and tours (unless custom protection settings were applied). That means the same file can be used and shared for multiple panos and tours.
    When hosting multiple panos and tours this is even a recommend way - use one global location for the krpano viewer and plugins files and refer from all other projects to them. With that updating the version will be much eaiser.

Viewer Embedding

Create anywhere on the html page a <div> element where the viewer should be embedded, give that div element an unique 'id' name and define its size via css styles:
<div id="pano" style="width:100%;height:100%;"></div>

After defining the <div> element, create a <script> element with the embedding script code.
For the embedding itself there is the global embedpano() function:

embedpano({...embedding parameters...});
  • The embedpano() function needs an object with the embedding parameters.

  • Full example:
    <script src="krpano.js"></script>
    <div id="pano" style="width:600px; height:400px;"></div>
      embedpano({xml:"pano.xml", target:"pano"});

Embedding Parameters

The embedpano() function needs a Javascript object as argument. This object is used to pass all parameters (in random order) by using parametername:value pairs. Almost all parameters (except the target parameter) are optional - when they were not defined, their default values will be used.
The parameters object provides the following settings:

  • Name and path to the startup xml file (relative to the html file).
  • When no xml file should be loaded on startup, don't set the value or use null.
  • Backward compatibility: When not set and a path to a swf file is set, then the filename of the swf file will be used (e.g. 'krpano.xml' for 'krpano.swf').

  • Set the target html-element where the pano viewer should get embedded.
  • Can be either the id of a html-element or directly the html-element itself.
  • There will be a Javascript alert() error when no target will be set or no html-element with the given id can be found.

  • The background color of the viewer (in html color format).
  • The default is #000000 (=Black).
  • Optionally the value transparent can be used to see the content (the website, bglayer layers) behind the pano.

    Note - when using a transparent background, only normal crossfade pano-blending will be supported (automatically).

  • Pass a Javascript Object with krpano variable:value pairs.
  • The variables will be set AFTER the xml file has been be loaded and parsed.
    So these variables can be used to add new settings or to overwrite settings that were already defined in the xml.
  • Example:
    var settings = {};
    settings["onstart"] = "trace('on start...')";
    settings["view.hlookat"] = 30;
    embedpano({xml:"pano.xml", target:"pano", vars:settings});

  • Pass a Javascript Object with krpano variable:value pairs.
  • This is basically the same as the vars setting, but these variables will be set BEFORE the xml file wil be loaded and parsed.
  • The main usage of this setting will be to set custom path variables that can be used as placeholders inside url paths in the xml files and / or to set variables that can be used inside xml-if-checks for <include> elements.
  • Example:
    embedpano({..., initvars:{mypath:"./panos1/"} });
  • To be able to pass initvars variables via http queries directly at the url of the html file this syntax need to be used:

  • Sets a custom path for resolving relative to the krpano viewer url paths.
  • Note - changing this will affect the %VIEWER% url placeholder.

  • A Boolean setting that defines if krpano log/trace-messages should be sent also to the browser Javascript console.

  • A Boolean setting to control the mouse-wheel support.
  • When set to true (the default), then the mouse-wheel events will be captured and can be used in the viewer (e.g. for zooming).
  • When set to false, then any mouse-wheel usage will be ignored and the browser will do its default mouse-wheel handling (typically scrolling the webpage).
  • The mouse-wheel support can be changed also at runtime by using the control.disablewheel setting.

  • A Boolean setting to control the captureing of touch events.
  • When set to true (the default), then the touch events will be captured and can be used in the viewer (e.g. for panning and zooming).
  • When set to false, then touch events itself will be still used by the viewer, but their default event processing will be not stopped. That means in this case the browser might pan or zoom the webpage.
  • The setting can be changed also at runtime by using the control.capturetouch setting.

  • A Boolean setting to give the viewer the input / keyboard focus on startup.
  • When not set, the setting will be set automatically depending on the viewer size - when the viewer will cover the whole webpage, focus will be set to true, otherwise to false.

  • Use WebGL for the rendering (recommended).
  • Instead of WebGL, CSS 3D-transforms could be used for displaying the panos, but compared to using WebGL this is very limited.
  • Settings:
    • true - Only use WebGL (the default).
    • false - Don't use WebGL, always use CSS 3D-transforms.
    • "auto" - Use WebGL when available, otherwise use CSS 3D-transforms.
  • When WebGL or CSS 3D-transforms are not available, an error will be shown.
  • Note - without WebGL these features are not available:
  • Note - depending on the Browser and device the number of WebGL elements on a single webpage is limited (e.g. to only 8 WebGL elements). When requesting more WebGL elements, then the least recently used one will get released.
    This needs to be considered when putting multiple panos on one single webpage. For simple panos/tours disabling WebGL for this usage case can be an option.

webglsettings:{preserveDrawingBuffer:false, depth:true, stencil:true, ...}
  • Pass an object with special settings for the WebGL context creation.
  • The WebGL context will be created at startup and can't be changed at runtime, therefore these settings need to be specified already during embedding.
  • Available settings:
    • webgl2 - Try using the WebGL 2.0 API when available. Set to false by default for the moment, because still slightly experimental and not fully tested across all systems.
      Current WebGL2 advantages in krpano:
      • Non-power-of-two textures also can use mipmapping.
      • Non-power-of-two textures can use repeatable texture-coordinates (needed for some .obj 3D-Models) without shader-workarounds.
    • preserveDrawingBuffer - Keep the drawing buffer content. Would need to be enabled for when trying to make screenshots of the WebGL canvas via toDataURL or readPixels in some browsers. Set to false by default for better performance.
    • depth - Create a depth buffer. Required for depthmap support and 3D-object rendering. Set to true by default, but could be disabled when not needed.
    • stencil - Create a stencil buffer. Required for a correct line rendering of polygonal-hotspots when using an alpha-transparent line-border color. Set to true by default, but could be disabled when not needed.
    • failIfMajorPerformanceCaveat - Don't use WebGL when the rendering performance would be dramatically lower than the OpenGL rendering performance of a native application. Set to false by default.
    • antialias - Set if anti-aliasing should be used - true or false.
      When not set, krpano decided itself for optimal performance because some device/browser/gpu combinations are performing very bad (e.g. half framerate) with enabled anti-aliasing. This setting should be used only for internal testing or very special cases.

  • Control the WebXR API support.
  • For using the WebXR API it is neccesady to do several initial setup-steps already on startup, therefore the usage of the WebXR API need to be defined already when embedding the viewer.
  • Available settings:
    • auto (the default)
      • Use the WebXR API only on desktop browsers and dedicated VR systems/browsers. On Android mobile systems the alternative krpano MobileVR support has a currently a better and wider device support.
      • When the WebVR API and the WebXR API are both available the same time, then prefer the WebVR API. Today the WebVR API is still the better choice. It allows using oversampling for higher image quality and device specific performance optimizations. Both is currently not possible with the WebXR API, eventually future API versions and browsers might get better here.
    • preferwebvr
      • Prefer the WebVR API when WebVR and WebXR are both available.
    • prefer or true
      • Prefer the WebXR API when WebVR and WebXR are both available.
    • no or false
      • Don't use the WebXR API at all, always use the WebVR API or the krpano MobileVR support for VR display.

  • A setting for optionally using a different global scale for mobile devices.
  • See also the xml stagescale setting.

  • Enable or disable the general Safe-Area support (for iOS devices with a notch).
  • Available settings:
    • auto (the default) - Automatically enable the Safe-Area support when the viewer gets embedded into a 'full-page' html-element.
    • true - Always enable the Safe-Area support. Could be used when the embedding-target-html-element is not full-page-sized during embedding.
    • false - Disable enable the Safe-Area support.
  • Note - in the html file there need to be also this <meta> setting in the html <head> element to be able to use the Safe-Area:
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, viewport-fit=cover">
  • More information: krpano Forum Post

  • A setting for optionally disabling the mouse support on touch devices.

  • Fake the krpano device detection settings.
  • Available settings: "mobile", "tablet", "desktop".
  • Note - This setting should be only used for internal testing, never for publishing!

  • The onready setting can be used to set a call-back-function to get notified when the embedding is done and the krpano viewer is ready for usage.
  • The given function will be called with the krpano Interface Object as parameter.
  • Example:
    embedpano({target:"id-of-your-div", onready:function(krpano)
      console.log("krpano is ready - version="+krpano.version);
        var hs = krpano.addhotspot();
        hs.type = "text";
        hs.html = "Test Hotspot";
        hs.ath = 20;
        hs.atv = 10;
        hs.onclick = function()

  • The onerror setting can be used to set a custom embedding-error-handling function.
  • The given function will be called with an error-message string as parameter.

  • With this setting it will be possible to pass/redirect http-query parameters from the url to the krpano viewer as variables.
  • Possible values:
    • true - pass all parameters to the viewer.
    • false - don't pass any parameters (the default).
    • "param1,param2,param3,..." - define a custom list of comma-separated parameters that are allowed to be passed.
  • Usage example:
  • Security Warning:
    When allowing all parameters (set to true) or parameters that can contain executable code to be passed, this can open potentials for Cross-site-scripting. If this can be a problem depends on the individual usage-case and the surrounding/containing website.

Viewer Removing

There are two ways for correctly removing a krpano viewer from the page and unloading / freeing all its allocated resources:

  • The removepano() function can to be called either with the id of the html target element or with an unique id that was defined during embedding
  • Example:
    embedpano({target:"panoDIV", id:"pano1"});

  • When having a krpano Interface Object (e.g. from onready callback) it is also possible to call its unload() function to remove the krpano viewer.
  • Example:
    embedpano({target:"id-of-your-div", onready:function(krpano)