Quickstart: Adding a TimePicker (HTML)

Article
08/10/2016

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

If you need to allow users to select a time in your application, for example to schedule a meeting or a reminder, you can use a TimePicker, which is a part of the Windows Library for JavaScript. The TimePicker displays three controls: one for the hour, one for the minute, and one to choose between AM and PM. These controls are easy to use with touch support, and they can be styled and configured in several different ways. (Windows only)

Objective: To demonstrate how to add a TimePicker.

Prerequisites

This topic assumes that you can create a basic Windows app using JavaScript. For instructions on creating your first app, see Creating your first Windows Store app using JavaScript.

Time to complete: 15 minutes.

Instructions

1. Creating a simpleTimePicker

As with most WinJS controls, you can create a TimePicker declaratively (as a data-win-control attribute on a <div> element) or imperatively (as an object in a JavaScript code block). In order for the control to appear, you should call WinJS.UI.processAll. If you are using Visual Studio project templates for Windows apps using JavaScript, this is done for you in the activated event handler.

This is how you create a TimePicker declaratively:

<!DOCTYPE html>
<html>
<head>
  <title>TimePicker Control Example</title>  
  <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet">
  <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
  <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>
    <body>
        <section>
            <h1> TimePicker Example</h1>
                <h3>Add a TimePicker Declaratively</h3>
                <div id="time" data-win-control="WinJS.UI.TimePicker"></div>
                <script type="text/javascript">
                    WinJS.UI.processAll(document.getElementById("time"));
                </script>
        </section>
    </body>
    
</html>

To create a TimePicker imperatively (in code), you do the following:

<!DOCTYPE html>
<html>
<head>
  <title>TimePicker Control Example</title>  
  <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet">
  <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
  <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>
   <body>
        <section>
            <h1> TimePicker Example</h1>
                <h3>Add a TimePicker Imperatively</h3>
                <div id="time" ></div>
                <script type="text/javascript">
                    var timeDiv = document.getElementById("time"); 
                    var timePicker = new WinJS.UI.TimePicker(timeDiv);
                </script>
        </section>
    </body>
</html>

When you build and run your solution, you will see three controls that display the current time, one for the hour, one for the minute, and one for AM or PM.

This how the TimePicker should look using the ui-dark.css file: TimePicker dark style

This is how the TimePicker should look using the ui-light.css file: TimePicker light style

2. Changing the default time

You can set a default time in the following ways:

Declaratively

<div data-win-control="WinJS.UI.TimePicker" data-win-options="{current='11:00:00'}"></div>

Imperatively

// "time" is the ID of the <div> element
var timeDiv = document.getElementById("time"); 
var timePicker = new WinJS.UI.TimePicker(timeDiv, {current:'11:00:00'});

You can format the time string in all the ways the JavaScript Date object allows, except for UTC values. Here are some examples:

03:20 pm
15:20:00

3. Specifying minute increments

You can change the way minutes are displayed in a TimePicker's minute control by setting the minuteIncrement property. For example, the following code causes the minute control to display minutes in multiples of 5.

<div data-win-control="WinJS.UI.TimePicker" data-win-options="{minuteIncrement:5}"></div>

4. Changing the way the minute and hour are displayed

You can change the pattern of the minute and hour. By default, the TimePicker displays a 2-digit hour, 2-digit minute, and AM/PM designator in the en-us locale. You can change this in the following ways.

To change the way the minute is displayed

var timePicker = WinJS.UI.TimePicker(timeDiv);

//does not display leading zeros
timePicker.minutePattern = "{minute.integer(1)}";

To change the way the hour is displayed


var timePicker = WinJS.UI.TimePicker(timeDiv);

//does not display leading zeros
timePicker.hourPattern = "{hour.integer(1)}";

To specify a 12-hour clock or a 24-hour clock

var timePicker = WinJS.UI.TimePicker(timeDiv);

//displays a 24-hour clock
timePicker.clock = "24HourClock";

//displays a 12-hour clock, plus "AM" or "PM"
timePicker.clock = "12HourClock";

The following list gives the possible values for the patterns you can use in a TimePicker:

{minute.integer} | {minute.integer(n)}
{hour.integer} | {hour.integer(n)}

5. Disabling a TimePicker

You can disable a TimePicker by setting its disabled property to true. As a result, the control is visible but dimmed and unavailable to the user.

var timePicker = new WinJS.UI.TimePicker(timeDiv);
timePicker.disabled = true;

6. Responding to the onchange event

You can use the change event to modify behavior in your application:

timePicker.onchange = hourChangeHandler; 

function hourChangeHandler(event) {
    // Insert code here.
    }

7. Changing the appearance of the TimePicker

In general, you can change the appearance of the TimePicker by using CSS styles.

<style id="text/css">
    [class="win-timepicker"] {background-color:LightBlue; }
</style>

and specifiying a TimePicker dropdown by using one of the following CSS classes:

win-timepicker
win-timepicker-hour
win-timepicker-minute
win-timepicker-ampm

For example, you can change the border color of the hour dropdown:

.win-timepicker-hour
{
    border: 3px solid rgb(28, 160, 218);
}

This causes the hour dropdown to appear with a blue border: TimePicker hour blue border

You can change the border color of the period (AM/PM) dropdown:

.win-timepicker-period
{
    border: 3px solid rgb(28, 160, 218);;
}

This causes the period dropdown to appear with a blue border: TimePicker period has blue border

You can specify all three TimePicker dropdown by using CSS attribute selector prefix syntax (^=), which finds every attribute whose name starts with the specified string:

[class^="win-timepicker"] { color:red; }

8. Showing and hiding the controls

You can specify whether a specific control is displayed by setting its display attribute to none:

.win-timepicker-minute { display:none; }

If you want to hide a control in only one instance of a TimePicker, you must reference the ID of the associated <div> element. For example, to hide the minute only for the TimePicker displayed in the <div> element with an ID of "time," do the following:

#time *.win-timepicker-minute { display: none; }

9. Displaying the TimePicker controls vertically

If you want to display the hour, minute, and AM/PM controls vertically instead of horizontally, you need to set the CSS attribute display on the controls. You must also set the display to block on the DIV itself.


#time {display:block;}
*[class^="win-timepicker"] { display: block; }

You can conditionally display the controls vertically, for example when the width of the screen falls below a specified limit. The following CSS media query specifies that the controls should be displayed vertically for all widths up to 320 pixels.

@media all and (max-width:320px) {
#time {display:block;}
*[class^="win-timepicker"] { display: block; }
}

10. Using pseudo-classes to style the TimePicker

The timePicker supports the following pseudo-classes that you can use as selectors to show certain styles when the TimePicker is in certain states.

win-timepicker:hover.The user places the cursor over the picker but does not activate it by clicking. Here the mouse is hovering over the hour dropdown.
win-timepicker:active. The picker is active after the user presses the control to open the dropdown and before he or she chooses an option.
win-timepicker:focus. The picker is highlighted to accept keyboard inputs.
win-timepicker:disabled. The picker cannot accept user interaction. The disabled property of the picker must be set to true for this pseudo-class.