Back Button

The back button in Magic Remote can let users navigate in your app. Your app should behave when users press the back button of the magic remote control as follows:

  • Move back to the previous screen.

  • If the current page is the entry page to your app, move back to the TV's Home screen.

For more about the mandatory guidance for webOS TV UX, see webOS TV UX Checklist.

Handling Back Button in App

In your app, you can combine the following options to handle the back button:

Using History API

By default, the platform itself handles the back button press on a magic remote control using the DOM's history object. Thus, if you want to customize back and forward navigation behavior, use the DOM's history object. When you move another page or state, add the current state to the history stack using history.pushState().

history.pushState(stateData, title, targetURL);

As long as something resides in the history stack, your webOS TV app receives the popstate event when a user presses the back button. You can subscribe to the popstate event using the History API or by adding a listener to the event, as shown below.

window.addEventListener("popstate", function(inEvent) {
	// received back, check inEvent.state if you want the data from the history push

In webOS TV, when a user presses the back button at the start point of your app, the screen control is passed on to the Home screen. The following diagram shows how the History object works and indicates when the Home screen should be displayed. If you set the disableBackHistoryAPI property to true and use the History API, you should customize the popstate event handler to open the Home screen manually.

Example chart of history object and back button using History API

Use the popstate events and pushState() method to keep track of the app state, and allow users to navigate back within your app.

To check the sample code on handling the back button press, see Back Button Control.

Handling Back Key Event

You can choose to make your app handle the back button press by receiving back key event. To handle the back button press as desired, indicate your intention on the appinfo.json file by setting the disableBackHistoryAPI property to true. This way can be useful especially if your app consists of a single page because taking track of history on a single-page app can be a real fuss.

To handle the back button press:

  1. Set the disableBackHistoryAPI property to true in appinfo.json file.

    	disableBackHistoryAPI: true;
  2. Add the back button keycode (0x1CD, 461 in decimal) in your event handler.

    window.addEventListener("keydown", function(inEvent){   
        if(window.event) {
            keycode = inEvent.keyCode;
        } else if(e.which) {
            keycode = inEvent.which;
    	switch (keycode) {
    		case 461: doBack(); break;
    		case 38: doUp(); break;
    		case 40: doDown(); break;

For more information on the magic remote control and key code of its buttons, see Remote Control.

Going Back to the Home Screen

In case of managing your app state manually (such as when you set the disableBackHistoryAPI property to true), sometimes your app needs to display the Home screen forcibly. To make a navigate back to the TV's Home screen, use the webOS prototype provided through the webOSTV.js file.

The following code shows one of the cases which is using the webOS.platformBack() method in back button event handlers:

<script type="text/javascript" src="webOSTVjs-1.1.0/webOSTV.js"></script>
function doBack() {
	// Do something for Back button();
	// If you need to open Home UI
	if (someCondition == true)

Also when you set disableBackHistoryAPI property to true and used the History API, you can use webOS.platformBack() as below:

window.addEventListener('popstate', function (event) {
	var data = event.state;
	if (data) {
		// do page move or anything else
	} else {
}, false);