WinJS.UI.NavBar object

Article
01/26/2017

[NavBar is no longer available for use as of Windows Library for JavaScript (WinJS) 4.2. Instead, use SplitViewCommand. ]

An app bar dedicated to navigation commands, typically located at the top of the display.

Explore this functionality in more depth as part of our App features, start to finish series: Flat navigation, start to finish (HTML) and Hierarchical navigation, start to finish (HTML)

Syntax

<div 
    data-win-control="WinJS.UI.NavBar">
</div>

var object = new WinJS.UI.NavBar(element, options);

Members

The NavBar object has these types of members:

Constructors
Events
Methods
Properties

Constructors

The NavBar object has these constructors.

Constructor	Description
NavBar	Creates a new NavBar.

Events

The NavBar object has these events.

Event	Description
onafterclose	Occurs immediately after the NavBar is closed.
onafteropen	Occurs immediately after the NavBar is displayed.
onbeforeclose	Occurs before the NavBar is closed.
onbeforeopen	Occurs immediately before the NavBar is opened.
onchildrenprocessed	Occurs after the NavBar has finished processing its child elements.

Methods

The NavBar object has these methods.

Method	Description
addEventListener	Registers an event handler for the specified event.
close	Closes the NavBar. Replaces the hide method.
dispatchEvent	Raises an event of the specified type and with specified additional properties.
dispose	Releases resources held by this NavBar. Call this method when the NavBar is no longer needed. After calling this method, the NavBar becomes unusable.
getCommandById	Returns the NavBarCommand object identified by id.
hideCommands	Hides the specified commands of the NavBar.
open	Opens the NavBar if it is not disabled. Replaces the show method.
removeEventListener	Removes an event handler registered through the addEventListener method.
showCommands	Shows the specified commands in the NavBar.
showOnlyCommands	Shows the specified commands in the NavBar while hiding all other commands.

Properties

The NavBar object has these properties.

Property	Access type	Description
ClosedDisplayMode	Read/write	ClosedDisplayMode gets or sets how the app bar is displayed when opened is true.
disabled	Read/write	Gets or sets a value that indicates whether the NavBar is disabled.
element	Read-only	Gets the HTML element that hosts this NavBar.
opened	Read-only	Gets a value that indicates whether the NavBar is not closed. (Replaces hidden property.)
placement	Read/write	Gets or sets a value that specifies whether the NavBar appears at the top or bottom of the main view.

Remarks

Known Issues

NavBars should be direct children of document.body. Otherwise, it is possible to mask event detection on the NavBar due to stacking context effects. This is because event detection for other elements is blocked while the NavBar is open. So, if the NavBar is a child of one of those blocked elements, it too will be blocked. This behavior is typical for all overlaying controls.

CSS classes

To customize the NavBar, you can define your own styles for these Cascading Style Sheets (CSS) classes (defined by the Windows Library for JavaScript style sheets):

CSS class	Description
win-navbar	Styles the entire NavBar.

Requirements

Minimum WinJS version	WinJS 2.0
Namespace	WinJS.UI

Share via