---
title: roHtmlWidget
slug: develop/rohtmlwidget
docTags:
createdAt: 2025-03-11T07:07:18.732Z
---
This object embeds the Chromium HTML rendering engine, which can be rendered at full screen or as a widget. You can display multiple *roHtmlWidget* instances at the same time. The JavaScript equivalent is [htmlwidget](docId\:pMpuH3A0VR8OhjoPsJwo7).
:::hint{type="success"}
**Tip**
Use the [roKeyStore](docId\:GhSZNW9eS8TEMURQXq-DU) object to provide client certificates for websites. Use the [roVirtualMemory](docId\:M2dQxiY5mGorAOSA8MVNi) object to set up a virtual memory repository for Chromium.
:::
## Object Creation
The *roHtmlWidget* object is initialized with an *roRectangle* object, which specifies the size and positioning of the widget on the screen, and an optional associative array, which defines properties for the widget.
```text
CreateObject("roHtmlWidget", rect As roRectangle, properties As roAssociativeArray)
```
The properties of an *roHtmlWidget* instance can be set with an associative array at initialization or with equivalent methods after initialization. Because many *roHtmlWidget* properties cannot be changed without reloading the page (and can produce unpredictable results if changed while the page is running), we recommend setting properties at initialization when possible, rather than using the equivalent methods.
:::hint{type="danger"}
Defining initialization properties for an *roHtmlWidget* instance disables some methods for that instance (e.g. `SetTransform()`, `AddFont()`, `SetUserStylesheet()`). See the “Available Methods with Initialization” section below for a list of available methods.
:::
## Initialization Parameters
The associative array passed during initialization can have the following parameters:
- `nodejs_enabled` bool: Enables [Node.js](docId\:vlSKfVzeQu04pD58rvXam)® on the widget. This value is `false` by default.
:::hint{type="info"}
Reloading a page which has Node.js enabled can be classified as an undefined behavior. The recommended method for restarting a Node instance is to destroy and rebuild the *roHtmlWidget*
:::
- `focus_enabled` bool: Enables focus for mouse/touchscreen events. This value is `true` by default.
- `mouse_enabled` bool: Enables mouse/touchscreen/USB keyboard events. This value is `false` by default.
- `scrollbar_enabled` bool: Enables automatic scrollbars for content that does not fit into the viewport. This value is `false` by default. The browser defaults to desktop-style scrollbars, but they can be [configured for mobile](docId\:qA8gmAIaHgVG5Gc6KdhF2) as well.
- `enable_pdf_viewer` bool: If this flag is not defined, or `false`, the default behavior is to generate a roHtmlWidgetEvent with `download-request` reason (legacy behavior). If the flag is enabled, the browser will render the PDF. This parameter is available as of BOS 9.1.116 and later versions.
- `pinch_to_zoom_enabled` bool: Enables pinch-to-zoom functionality. This value is `false` by default.
- `force_gpu_rasterization_enabled` bool: Enables GPU rasterization for HTML graphics. By default, the decision to use GPU rasterization is based on [internal Chromium logic](https://www.chromium.org/developers/design-documents/chromium-graphics/how-to-get-gpu-rasterization).
:::hint{type="info"}
This setting has been deprecated. As of OS8, GPU rasterization is enabled by default and setting this property has no effect.
:::
- `canvas_2d_acceleration_enabled` bool: Enables 2D canvas acceleration. This will improve the framerate of most HTML pages that use 2D animations, but can cause out-of-memory issues with pages that use a large number of off-screen canvas surfaces.
:::hint{type="info"}
This setting has been deprecated. As of OS8, Canvas acceleration is enabled by default and can be disabled by setting this flag to `false`.
:::
- `javascript_enabled` bool: Enables JavaScript on the widget. This value is `true` by default.
- `brightsign_js_objects_enabled` bool: Enables [BrightScript-JavaScript objects](docId\:URrXhU7L-V9ea-Zhy0JV3). This value is `false` by default.In OS 8.2.55.4 and later, html widgets that are loaded from HTTP/HTTPS protocols do not share the same local storage database (html widgets that are loaded via file protocol act as they did in previous releases). These flags allow you to change the default behavior of widgets loaded through HTTP/HTTPS from "unshared" to "shared", or to change the default behavior of widgets with locally loaded files to "unshared" from "shared":
- `force_shared_storage` bool: Allows HTML widgets loaded via HTTP/HTTPS protocol to share local storage if they are loaded from the same domain.
- `force_unshared_storage` bool: Prevents HTML widgets loaded via FILE protocol from sharing storage.
- `transform` string: Sets the screen orientation of content in the widget (note that the coordinates and dimensions of the *roRectangle* containing the widget are not affected by rotation). The following values are accepted:
- `"identity"`: There is no transform (i.e. the widget content is oriented as landscape). This is the default setting.
- `"rot90"`: The widget content is rotated anticlockwise to portrait at 90 degrees.
- `"rot180"`: The widget content is rotated anticlockwise to portrait at 180 degrees.
- `"rot270"`: The widget content is rotated anticlockwise to portrait at 270 degrees.
- The following additional transforms are supported from BOS 9.1.145 and 10.0.15:
- `mirror`: Horizontal mirror transformation
- `mirror_rot90`: Mirrored 90 degree clockwise rotation
- `mirror_rot180`: Mirrored 180 degree clockwise rotation
- `mirror_rot270`: Mirrored 270 degree clockwise rotation
- `user_agent` string: Modifies the default user-agent string for the *roHtmlWidget* instance.
- `url` string: The URL to use for display. See the [SetUrl()](docId\:xljq5_YhDmA2SSmpZimtK) entry below for more information on using URIs to access files from local storage.
- `language` string: Specifies the language to load the web page in.
- `user_stylesheet` string: Applies the specified user stylesheet to pages in the widget. The parameter is a [URI](docId\:xljq5_YhDmA2SSmpZimtK) specifying any `file:` resource in the storage, unless you are using a CSS stylesheet saved to the SD card, in which case you should use `sd:/path/filename.css`. The stylesheet can also be specified as inline data.
- `hwz_default` string: Specifies the default [HWZ](docId\:e6uJleH69Q0JmMv8kyTrp) behavior. This value is `off` by default. To enable it, set it to `on`.
- `storage_path` string: Creates a "Local Storage" subfolder in the specified directory. This folder is used by local storage applications such as the JavaScript *storage* class.
- `storage_quota` string or double: Sets the total size (in bytes) allotted to all local storage applications (including IndexedDB). A BrightScript integer is only guaranteed to be able to represent a count of bytes up to 2GB so avoid using integers when calculating the size: Use float or double instead since they can represent values over 2GB (string can also be used but is not recommended). If the storage path is specified without a storage quota, Chromium defaults to reserving 1GB plus 10% of the total size of the storage device.
- `port` roMessagePort: Configures the message port to which the *roHtmlWidget* instance will send events. When using initialization parameters, the `port` parameter should be used instead of the `SetPort()` method to ensure the script can catch `load-started`, `load-finished`, and `load-error` events.
- `fonts` roArray: Specifies a list of font files that can be accessed by the webpage. Font files are specified as an array of string filenames. Supported font types include TrueType Font files (*.ttf*) and Web Open Font files (*.woff*). See [this page](docId\:XleiD0O22LAz9SpXtbd8V) for more information about supported fonts.
- `pcm_audio_outputs` roArray: Configures the PCM audio output for the HTML widget. Outputs are specified as an array of strings, each string being the name of an output. (See [roAudioOutput documentation](docId\:Olycd6IjE_FNAXDzJhDkR) for a list of acceptable names.)
- `compressed_audio_outputs` roArray: Configures compressed audio output (e.g. Dolby AC3 encoded audio) for the HTML widget. Outputs are specified as an array of *roAudioOutput* instances.
- `multi_channel_audio_outputs` roArray: Configures multi-channel audio output for the HTML widget. Outputs are specified as an array of *roAudioOutput* instances.
- `inspector_server` roAssociativeArray: Configures the [Chromium Inspector](docId:4qlK1krr1cnx7xypWXRY5) for the widget. Starting in BrightSign OS 8.5.31 you will need to also set the enable\_web\_inspector registry key (in the "html" section) to enable the JavaScript console. In “enable\_web\_inspector”, "1" will allow the inspector and "0" or not present will disable it. A reboot will be needed for these changes to take effect (if you enable/disable this through the LDWS UI it may trigger a reboot to apply the changes).
- `ip_addr` string: The Inspector IP address. This value is useful if the player is assigned more than one IP address (i.e. there are multiple network interfaces) and you wish to limit the Inspector server to one. The default value is `"0.0.0.0"`, which allows the Inspector to accept connections using either IP address.
- `port` int: The port for the Inspector server. Note that the BOS 9.1.47 Beta release always uses port 2999. In the official 9.1 GA release, this parameter will be configurable with registry settings. Set the html > enable\_web\_inspector registry flag to change the web inspector port from the default value of 2999.
:::hint{type="danger"}
For security reasons, *enable\_web\_inspector* should only be used in non-production presentations. Make sure to disable JavaScript console before publishing to a production environment. In the Chromium version found in BOS 8.5.31 and beyond, the JavaScript console will log information in memory even when you are not connected to the inspector. This will consume memory until the player runs out, which will result in a crash.
:::
- `security_params` roAssociativeArray: Enables or disables Chromium security checks for cross-origin requests, local video playback from HTTP, etc.
- `websecurity` bool: Enables Chromium security checks for cross-origin requests.
- `camera_enabled` bool: Enables webpage access to USB cameras connected to the player (access is disabled by default). This allows support for WebRTC applications.
- `insecure_https_enabled` bool: Instructs the widget to ignore security errors when connecting to insecure HTTPS hosts (insecure HTTPS is disabled by default). Enabling this feature makes the player insecure; it is not suitable for production environments and should only be used for testing.]
- `audio_capture_enabled` bool: Gives access to audio input devices and lets Chromium enumerate all audio input and output devices
- `trusted_iframes_enabled` bool: Controls if content loaded in iframes is permitted access to Node.js, JavaScript APIs, and BrightSign-JavaScript objects.
- To enable Node in iframes, initialize `nodejs_enabled` and `security_params.trusted_iframes_enabled` to be `true`.
- To enable both [JavaScript APIs](docId\:o2uIyNVKbsyd1qXCvhVCN) and [BrightSign-JavaScript](docId\:URrXhU7L-V9ea-Zhy0JV3) objects in iframes, initialize `brightsign_js_objects_enabled` and `security_params.trusted_iframes_enabled` to be `true`.
:::Paragraph{indent="3"}
This flag will be available for BOS versions 9.1.75.3 and later. It will result as a failure to load HTML widget if used in earlier versions.
:::
- With BOS 8.2 and later (Chromium69 and later), several new CORS checks have been added: `security_params.websecurity` or `enableSecurity(false)` do not disable all these checks. Use the following registry setting instead: `registry write html disable-web-security 1` . To write this to the registry using [roRegistrySection](docId\:FfM73tjd_BThW4-P-0JVG):
```text
RegHtml = CreateObject("roRegistrySection", "html")
RegHtml.Write("disable-web-security", "1")
RegHtml.Flush()
```
- This flag will take effect on all `roHtmlWidget` instances, as opposed to previous flags which are only effective on the instance they are called on.
:::hint{type="info"}
The `camera_enabled` parameter is currently supported on the XTx44/43, XDx34/33, HDx24/23, LS424/LS423, and 4Kx42 models.
:::
- `javascript_injection` roAssociativeArray: Specifies JavaScript code to inject at different initialization points (JavaScript code can also be injected during runtime using the `InjectJavaScript()` method). The associative array can contain three parameters (described below). Each parameter value is an array of associative arrays, each containing a single key/value pair. The array must contain a `source` key. The `source` value is a string that can contain any of the following: pure JavaScript code, a path to a JavaScript file, or a base64-encoded string (i.e. beginning with `data:text/javascript;charset=utf-8;base64,` ). Mutliple `source` keys can be included, but the load order will be unpredictable. The array can also contain the optional `world` key, which can be assigned one of the following values: `"application"`, `"user"`, or `"main"` (see [this page](http://doc.qt.io/archives/qt-5.6/qwebenginescript.html#ScriptWorldId-enum) for more details); if the `world` parameter is not included in the array, `"application"` is selected by default.
- `document_creation`: The script will run as soon as the document is created. This behavior is not suitable for any DOM operation.
- `document_ready`: The script will run as soon as the DOM is ready. This behavior is equivalent to the `DOMContentLoaded` event firing in JavaScript.
- `deferred`: The script will run when the page load finishes.
:::hint{type="warning" indent="1"}
The path to the JavaScript file(s) must be relative to the root of the default storage. The JavaScript file(s) must be present in the filesystem, and can also be an asset in the assetpool. Data URLs are also accepted.
:::
```text
config = {
javascript_injection: {
document_creation: [{source: "0.js" }],
document_ready: [{source: "1a.js" }, {source: "1b.js" }],
deferred: [{source: "2.js" }]
},
url: "..."
}
```
- `assets` roArray: Allows the *roHtmlWidget* instance to [access one or more asset pools](docId\:xljq5_YhDmA2SSmpZimtK). If a file exists in multiple specified asset pools, the asset pool with the lowest index in the array has precedence. Each array entry is an associative array containing information about an asset pool:
- `pool` roAssetPool: An asset pool containing files
- `collection` roAssetCollection: A manifest identifying the files in the pool
- `uri_prefix` string: The URI prefix of the webpage resources to retrieve from the pool
- `pool_prefix` string: The pool prefix that will replace the URI prefix when looking up the resource in the pool
- `user_data` object: Sets the user data that will be returned when events are raised. This is available as of BOS version 9.1.84 and later.
## ifHtmlWidget
### GetFailureReason() As String
Gives more information when a member function returns `false`.
### Hide() As Boolean
Hides the widget.
### Show() As Boolean
Shows the widget.
### raise()
Raises the html widget above all other graphical elements on screen (including other html widgets).
### lower()
Lowers the html widget below all graphical elements on screen.
### SetRectangle(r As roRectangle) As Boolean
Changes the size and positioning of the widget rectangle using the passed *roRectangle* object.
### SetURL(URL As String) As Boolean
Displays content from the specified URL. When using this method to retrieve content from local storage, specify the file location as follows: `"file:/://"`. For example, an *index.html* file in the "Content" folder on the SD card can be selected with the string `"file:/SD:/Content/index.html"`. You can also omit the drive specification to select the currently active drive (i.e. whichever drive the current autorun as loaded from).
### AddAuthenticationCredentials (url As String, username As String, password As String) As Boolean
Tells Chromium to use the specified username and password when retrieving the given URL.
### MapFilesFromAssetPool(asset\_pool As roAssetPool, asset\_collection As roAssetCollection, pool\_prefix As String, uri\_prefix As String) As Boolean
Sets the mapping between the URL space and the pool files. HTML content that has been deployed via BrightAuthor will typically reside in the pool and have encrypted SHA1-based filenames. A mapping mechanism is required to allow any relative URIs contained in the HTML content to continue working and to locate the appropriate resources in their respective pool locations.
You can use this method to bind part of the resource URI space onto pool locations. This method accepts the following arguments: an *roAssetPool* object containing assets, an *roAssetCollection* object identifying the assets, and two semi-arbitrary strings (URI\_PREFIX and POOL\_PREFIX).
Any URI in the form `"file:/[URI_PREFIX][RESOURCE_ID]"` will be rewritten into the form `"[POOL_PREFIX][RESOURCE_ID]"`. It will then be located in the pool as if that name had been passed to the *roAssetPoolFiles.GetPoolFilePath()* method. This binding occurs for every instance of *roHtmlWidget*, so different mappings can be used for different bundles of content.
### SetZoomLevel(scale\_factor as Float) As Boolean
Adjusts the scale factor for the displayed page (the default equals 1.0).
### EnablePinchToZoom(enable as Boolean) As Boolean
Enables or disables pinch-to-zoom functionality, which is disabled by default.
### EnableSecurity(enable As Dynamic) As Boolean
Deprecated. Use `security_params` in initialization parameters instead.
### EnableMouseEvents(enable As Boolean) As Boolean
Deprecated. Use `mouse_enabled` in initialization parameters instead.
### SetPortrait(portrait\_mode As Boolean) As Boolean
Deprecated. Use `transform` in initialization parameters instead.
### SetTransform(transform As String) As Boolean
Sets the screen orientation of content in the widget (note that the coordinates and dimensions of the *roRectangle* containing the widget are not affected by rotation). This method accepts the following strings:
- `"identity"`: There is no transform (i.e. the widget content is oriented as landscape). This is the default setting.
- `"rot90"`: The widget content is rotated to portrait at 90 degrees (clockwise).
- `"rot270"`: The widget content is rotated to portrait at 270 degrees (counter-clockwise).
The following additional transforms are supported from BOS 9.1.145 and 10.0.15:
- `mirror`: Horizontal mirror transformation
- `mirror_rot90`: Mirrored 90 degree clockwise rotation
- `mirror_rot180`: Mirrored 180 degree clockwise rotation
- `mirror_rot270`: Mirrored 270 degree clockwise rotation
:::hint{type="info"}
The JavaScript `onload` event will report landscape dimensions for a window that is rotated with the `SetPortrait()` or `SetTransform()` method. If your application relies on the `onload` event to retrieve window dimensions, we recommend instead using the roHtmlWidget `transform` initialization parameter, which ensures the HTML window is initialized with portrait dimensions.
:::
### SetAlpha(alpha As Integer) As Boolean
Sets the overall alpha level for the widget (the default equals 255).
### EnableScrollbars(scrollbars As Boolean) As Boolean
Deprecated. Use `scrollbar_enabled` in initialization parameters instead.
### AddFont(filename As String) As Boolean
Deprecated. Use `fonts` in initialization parameters instead.
### SetPcmAudioOutputs(outputs As roArray) As Boolean
Deprecated. Use `pcm_audio_outputs` in initialization parameters instead.
### SetCompressedAudioOutputs(outputs As roArray) As Boolean
Deprecated. Use `compressed_audio_outputs` in initialization parameters instead.
### SetMultichannelAudioOutputs(outputs As roArray) As Boolean
Deprecated. Use `multi_channel_audio_outputs` in initialization parameters instead.
### SetHWZDefault(default As String) As Void
Deprecated. Use `hwz_default` in initialization parameters instead.
### SetVideoPlayerDefaults(defaults As roAssociativeArray) As Boolean
Sets default playback settings for `