Prompting Users to Pin your Site

The encourages users to pin the site to the taskbar using a drag-and-drop operation.

This task explains how to use the Pinned site API to add a website shortcut to the Windows Start menu and launch a Pinned site browser window. It also describes how you might promote site pinning functionality and encourage users to pin sites to the Windows 7 taskbar. To learn how a user can pin a site by using the mouse or keyboard shortcuts, see Introduction to Pinned Sites.

  • Detecting levels of browser and operating system support for pinning sites
  • Two Ways to Get a User to Pin Your Site
    • Method Introduced in this Task
    • Adding a site to the Start menu
    • Prompting users to drag the site icon
  • Real world example
  • Next Steps
  • Related topics

Detecting levels of browser and operating system support for pinning sites

This section introduces the pinnedSiteDetection.js helper script; which can be found here. This script helps detect the capability of the user's browser and the operating system on which it is running. This is important because you do not want to display a UI that has no functionality.

The following table shows all the information that the pinnedSiteDetection.js helper script can discover:

Looking for Details
Does the browser support pinning?

Is your user using a browser that supports pinning?

If so, what level of 'pin' support is provided?

If the site is Pinned...

Is your user currently visiting your site from a pin?

If the site has been Pinned...

Has your user pinned in the past?


Is the operating system that your user is using able to support pinning?

If so, what level of support is possible?


There are three levels of browser support for pinning sites:

  • Full pin capability -- the user has Windows 7 and Windows Internet Explorer 9, or Internet Explorer 10 and Windows 8 installed. This means that the user can drag the site icon to the taskbar to pin the site.
  • Limited pin capability -- the user has Internet Explorer 9 installed, but has not installed Windows 7. This means that user can pin sites, but those sites have to be pinned to the Start menu.
  • No pin capability -- the user has not installed Internet Explorer 9 nor Windows 7. The user can use Pinned sites if they upgrade to Internet Explorer 9.

The following example code shows how to detect the level of support for pinned sites in the user's current browser:

function doChecks_Browser() {    
    // full pin abilities == can pin && Win7+    
    if (pinnedSiteDetection.hasFullPinAbilityBrowser)        
        document.getElementById("cellCanPinFull").bgColor = "green";
        document.getElementById("cellCanPinFull").bgColor = "gray";
    // limited pin abilities == can pin && not Win7+ 
    if (pinnedSiteDetection.hasLimitedPinAbilityBrowser)        
        document.getElementById("cellCanPinLimited").bgColor = "green";
        document.getElementById("cellCanPinLimited").bgColor = "gray";    
     // no pin abilities == cannot pin     
     if (pinnedSiteDetection.hasNoPinAbilityBrowser)        
         document.getElementById("cellCanNotPin").bgColor = "green";
         document.getElementById("cellCanNotPin").bgColor = "gray";

Two Ways to Get a User to Pin Your Site

Method Introduced in this Task

Use the following method when the user has limited pin support (using Windows Vista and Internet Explorer 9); otherwise, use the preferred method of allowing the user to drag the icon to his or her taskbar:


The window.external.msAddSiteMode method adds the current webpage to the Windows Start menu under All Programs and launches the webpage as a Pinned site. The website is not pinned to the taskbar by default.

This method must be invoked by a user action, such as clicking a button, where the user is given an opportunity to confirm the action.

Adding a site to the Start menu

Most users of Internet Explorer pin a site by dragging the site icon or tab to the Windows taskbar. This is the preferred method of pinning sites and is described in the Prompting users to drag the site icon section.

The Tools menu provides another option to pin the site called Add site to Start menu. This is exactly the action that the msAddSiteMode method performs. Because of its location on the Tools menu, far fewer users are expected to find and use this option.

The following code shows one way to expose this functionality on a webpage.

function addSite()
    try {
    catch (e) {
        alert("This feature is only available in Internet Explorer 9.");
<button onclick="addSite();">Add Site to Start Menu</button>

In response to a button click, the msAddSiteMode method launches the Add site to Start Menu dialog box, so the user can confirm the action. If the browser does not support the method, the try/catch block provides simple feedback that the requested action failed.

Note  The msAddSiteMode method must be invoked by a user action, such as clicking a button. You cannot install a Start menu shortcut or pin a site to the taskbar without user interaction.


Pinning applications and websites to the taskbar is completely in the user's control. To keep the user in total control of their taskbar, adding a Pinned site shortcut to the Start menu does not automatically pin the site to the taskbar. Instead, the user must pin the program to the taskbar after the website is running.

There are better ways to accomplish this goal. Consider the following:

  • Why wait to determine whether the user is browsing with Internet Explorer 9 or a later version? You can easily detect whether the Pinned site features are supported by the browser before displaying any UI.
  • The recommended user experience is drag-and-drop. Your users are not likely to click a button or link if they do not know what to expect. By comparison, pinning a site to the taskbar with a drag-and-drop operation seems more natural. This is the experience you should optimize for.

Prompting users to drag the site icon

Users are more likely to use a drag-and-drop operation if your site includes a visual cue, such as the message in the following screenshot:

The code is straightforward and includes a fixed position div element that contains an image, text, and a link.

<div id="divPinSite">
    <img src="Images/whitearrow.ico" alt=""/>
    Drag the site icon to the taskbar to pin site
    <a href="javascript:void(0)" onclick="addSite();">
    Or, click here to add to Start menu</a>

The following CSS styles finish the effect. The div and its child elements float over the background of the page.

<style type="text/css">
    position: fixed;
    padding: 5px;
    color: white;
    width: 380px;
    height: 20px;
    top: 0px;
    left: 70px;
    background-color: #c00;
    border-radius: 0px 0px 10px 10px;
    font-size: .87em;
    font-family:Arial, Helvetica, sans-serif;
#divPinSite img
    height: 16px;
    width: 16px;
    vertical-align: top;
    float: left;
    margin-right: 5px;
#divPinSite a
    float: left;
    padding-top: 1em;
    text-decoration: none;
    color: black;
    font-size: smaller;

Of course, there is no reason to display the prompt unless the user is browsing with Internet Explorer 9 or later, so the CSS includes "display:none" to initially hide the div element from view. The following script runs as the page loads to determine whether to show the prompt.

window.onload = function()
    try {
        if (window.external.msIsSiteMode()) {
            // Continue intialization
        else {
            document.getElementById('divPinSite').style.display = "block";
    catch (e) {
        // Fail silently. Pinned Site API not supported.

Real world example

The following screenshot shows how the Huffington Post prompts users to pin the site by using a page banner that scrolls downward from the top of the screen.

Next Steps

Instead of pointing to off-screen elements in the browser frame, you can easily declare your own images that a user can drag to pin. For more information, see Dragging an Image to Pin the Site.

After the user pins your site, you might want to advertise specific Pinned site features. For more information, see Creating a First-run Experience.


Customizing the Site Icon

Declaring Pinned Site Metadata

Detecting a Pinned Site


Fresh Tweets 2.0 - demo for Windows 8

High Quality Visuals for Pinned Sites in Windows 8

How to Improve Discoverability

Introduction to Pinned Sites

Pinned Sites in Windows 8