Fork me on GitHub

Working With Widgets

The TV Application Layer provides a number of ready-made widgets to help you build your application interface. You can use these widgets out-of-the-box, or extend them for re-use in your applications.

This page lists all the framework widgets, but there are some other important topics relating to widgets:


This is the base widget, all other widgets are subclasses of this.

See widget.js.


The super class for all widgets that can contain other widgets.

See container.js.


A dynamically loadable re-usable block of UI. See Components for detailed documentation.

See component.js for the Javascript documentation.


A placeholder into which to load Components. See Components for detailed documentation.

See componentcontainer.js for the Javascript documentation.


A UI element that can obtain spatial navigation focus. See the focus management overview.

The button widget is the only widget that is currently able to receive focus. When a button is focused, pressing the VK_ENTER key will fire a select event.


A Button usually contains either a Label , Image or Container but could contain any component (It does not make sense to put anything inside a button that deals with navigation though).

var okButton = new Button("okButton");
var okButtonText = new Label("okButtonLabel", "ok");

var cancelButton = new Button("cancelButton");
var cancelButtonText = new Label("cancelButtonLabel", "cancel");

See button.js for the Javascript documentation.

See Creating a Formatter to learn how to create a button using a formatter.


A UI Text element.

See label.js for the Javascript documentation.


An image.

See image.js for the Javascript documentation.


The List widget holds a linear collection of UI elements. It has two direct subclasses HorizontalList and VerticalList. As the List has no intrinsic styling, the only difference between a HorizontalList and a VerticalList is their response to user input. A HorizontalList is navigated with left and right, and a VerticalList is navigated with up and down.


You can either fill a List with child UI elements directly:

list.appendChildWidget(new Button('button_id'));

or associate a DataSource with a List to populate list data from an array object: (see Data Binding).

var verticalList = new VerticalList("verticalList", formatter, dataSource);

See also:


Wrapper widget for list items when the list’s render mode is RENDER_MODE_LIST.

See listitem.js for the Javascript documentation.


A list where items are navigated between using VK_LEFT and VK_RIGHT.

Horizontal List

See horizontallist.js for the Javascript documentation.


A list where items are navigated between using VK_UP and VK_DOWN.

Vertical List

See verticallist.js for the Javascript documentation.


A 2D grid of containers which can be navigated between using VK_LEFT, VK_RIGHT, VK_DOWN and VK_UP.

See grid.js for the Javascript documentation.


A carousel is a sideways scrolling list, in which an item can be focused using VK_LEFT and VK_RIGHT. The list elements are scrolled as the user navigates, so that the focused element remains in the centre of the carousel.

Carousels can have various wrap modes:

  • WRAP_MODE_NONE – The carousel is bookended - you can’t navigate through all elements in a full circle
  • WRAP_MODE_NAVIGATION_ONLY – You can circle through all elements, however there is a visual break at the end of the carousel before you move back to the first element
  • WRAP_MODE_VISUAL – You can circle through all elements, and items at the beginning of the carousel are visible from the end of the carousel, so it forms a continuous loop

The default setting is WRAP_MODE_VISUAL. You can set the wrap mode using: horizontalCarousel.setWrapMode(HorizontalCarousel.WRAP_MODE_NONE);

Carousels are designed to be constructed via Data Binding

Horizontal Carousel

See horizontalcarousel.js for the javascript documentation.


Video and audio playout. Note: Do not construct a Media widget directly. Use Device.createPlayer(...)

See Media Playback for more details, and media.js for the javascript documentation.


Indicates a position via a horizontal progress bar (must be styled by the application).

Horizontal Progress

See horizontalprogress.js.


Allows a value to be set by sliding a control along a slider using VK_LEFT and VK_RIGHT.

See horizontalslider.js for the javascript documentation.


Extends HorizontalSlider to also allow the indication of a buffered range.

Scrub Bar

See scrubbar.js for the javascript documentation.


Versatile on-screen keyboard, with keys laid out on a grid. Note that to enable focus on the keyboard keys, you must first set the active child key, for example:


Key Board

See keyboard.js for the Javascript documentation.


Allows large blocks of text to be paged.

Text Pager

See textpager.js for the javascript documentation.

Creating New Widgets

To create a new widget, extend the base Widget, Container or another one of the built-in widgets.

You must implement the render(device) method, which must return an output element (generated from the createX (e.g. createContainer) methods implemented by the provided device. If your widget extends Container you are also responsible for rendering the children (by calling their render methods).

The render() method must also set the outputElement property on the widget with the same value as it returns. For performance reasons, you should not re-render a widget if it already has an outputElement set, instead you should update this element.

An example implementation of the render method is:

  if(!this.outputElement) {
    this.outputElement = device.createContainer(, this.getClasses(), "#");
      for(var i=0; i<this._childWidgetOrder.length; i++) {
        device.appendChildElement(this.outputElement, this._childWidgetOrder[i].render(device));
  return this.outputElement;