WinJS.UI.Pages.PageControl object

A modular unit of HTML, CSS, and JavaScript defining a page within an app that can be navigated to or used as a custom Windows Library for JavaScript control.


var pageControl = WinJS.UI.Pages.define(uri, members);


The PageControl object does not define any members.

PageControl Members

A PageControl doesn't have any members other than the ones you define when you call the WinJS.UI.Pages.define to create it.

Creating a PageControl

Unlike other Windows Library for JavaScript controls, you don't instantiate a PageControl directly. Instead, you create a PageControl by calling the WinJS.UI.Pages.define method and passing it the URI of the HTML file that defines the PageControl and an object that defines the PageControl members.

Here's a an example of a PageControl definition. It's made up of three files: an HTML file, a CSS file, and a JavaScript file.

<!-- samplePageControl.html -->
<!DOCTYPE html>
    <meta charset="utf-8">

    <!-- WinJS references -->
    <link href="/pages/samplePageControl.css" rel="stylesheet">
    <script src="/pages/samplePageControl.js"></script>
    <div class="samplePageControl">
        <p class="samplePageControl-text"><span data-win-bind="textContent: controlText">Message goes here</span>
        <button class="samplePageControl-button">Click me</button></p>
        <p>Page controls can also contain Windows Library for JavaScript controls. They are activated automatically.</p>
        <div class="samplePageControl-toggle" data-win-control="WinJS.UI.ToggleSwitch"></div>
/* samplePageControl.css */
    padding: 5px;
    border: 4px dashed #999999;
// samplePageControl.js
(function () {
    "use strict";

    var ControlConstructor = WinJS.UI.Pages.define("/pages/samplePageControl.html", {
        // This function is called after the page control contents
        // have been loaded, controls have been activated, and
        // the resulting elements have been parented to the DOM.
        ready: function (element, options) {
            options = options || {};
            this._data ={ controlText: options.controlText, message: options.message });

            // Data bind to the child tree to set the control text
            WinJS.Binding.processAll(element, this._data);

            // Hook up the click handler on our button
            WinJS.Utilities.query("button", element).listen("click",
                // JavaScript gotcha - use function.bind to make sure the this reference
                // inside the event callback points to the control object, not to
                // window

            // Windows Library for JavaScript controls can be manipulated via code in the page control too
            WinJS.Utilities.query(".samplePageControl-toggle", element).listen("change",

        // Getter/setter for the controlText property.
        controlText: {
            get: function () { return this._data.controlText; },
            set: function (value) { this._data.controlText = value; }

        // Event handler that was wired up in the ready method
        _onclick: function (evt) {
            WinJS.log && WinJS.log(this._data.message + " button was clicked", "sample", "status");

        // Event handler for when the toggle control switches
        _ontoggle: function (evt) {
            var toggleControl =;
            WinJS.log && WinJS.log(this._data.message + " toggle is now " + toggleControl.checked, "sample", "status");

    // The following lines expose this control constructor as a global.
    // This lets you use the control as a declarative control inside the
    // data-win-control attribute.

    WinJS.Namespace.define("Controls_PageControls", {
        SamplePageControl: ControlConstructor

Displaying a PageControl

Once you've defined your PageControl, there are a few ways you can display it:

  • Use the WinJS.UI.Pages.render function.

    <div class="renderingPageControls-renderedControl"></div>
    // Render the page control via a call to WinJS.UI.Pages.render. This lets
    // you render a page control by referencing it via a url.
    var renderHost = element.querySelector(".renderingPageControls-renderedControl");
    WinJS.UI.Pages.render("/pages/SamplePageControl.html", renderHost, {
        controlText: "This control created by calling WinJS.UI.Pages.render",
        message: "Render control"
  • Publicly expose the PageControl object's constructor and use it to create the PageControl.

    <div class="renderingPageControls-createdProgrammatically"></div>
    // Render the page control by creating the control.
    var constructedHost = element.querySelector(".renderingPageControls-createdProgrammatically");
    new Controls_PageControls.SamplePageControl(constructedHost, {
        controlText: "This control created by calling the constructor directly",
        message: "Constructed control"
  • Use the WinJS.UI.Pages.get function to get a constructor for the PageControl.

  • Instantiate the control in HTML as if it were a Windows Library for JavaScript control (which it is). You must publicly expose the PageControl object's constructor for this to work.

    <div data-win-control="Controls_PageControls.SamplePageControl"
        data-win-options="{controlText: 'This was created declaratively', message: 'Declarative control' }">
  • Use an HtmlControl to render the page.

     <div class="renderingPageControls-htmlControl" data-win-control="WinJS.UI.HtmlControl"
        data-win-options="{uri: '/pages/samplePageControl.html',
        controlText: 'This was rendered via the HtmlControl', 
        message: 'HTML Control loaded control' }"></div>


Minimum WinJS version

WinJS 1.0



See also

For developers

WinJS.UI.Pages Namespace

Your first app - Part 3: PageControl objects and navigation

Navigating between pages

Quickstart: Using single-page navigation

Quickstart: Adding Page controls

Adding a Page control item template

HTML Page controls sample

Navigation and navigation history sample

For designers

Navigation patterns