The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WinJS.UI.Pages.PageControl object

Applies to Windows and Windows Phone

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