Share via

How to customize Start screen tiles for desktop apps (Windows Runtime apps)

  • Article

As of Windows 8.1, Win32 app developers can customize the look of a desktop app's tile on the Start screen. In Windows 8, these tiles were only supplied by the system, with no option for customization by the developer. The app's icon was shown in a tile based on the Start screen's background color. Windows 8.1 provides a more varied default tile appearance, but also allows you to further brand your tile with your own colors and images.

Customizations available for your desktop app tile are:

  • Custom, full-bleed images
  • A specified background color
  • The option to show or hide the app name on the tile
  • Specified light or dark text color if you choose to show the app name

You can fully customize a tile, but you also should be aware of changes to the default tile appearance, which might be enough for you. The default tile that Windows assigns to your app is still a medium tile that shows the app name and the app's icon. However, as of Windows 8.1, the layout has changed and Windows pulls a color from the app's icon to provide a similar or complementary background color around that icon.

The following image shows how the same default tiles look in Windows 8 and Windows 8.1, using the same Start screen background color.

Microsoft Office tiles shown for Windows 8 and Windows 8.1

If you choose to further customize your tile, you'll do that through a specialized XML file. The schema used by this file is similar to the tile schema used for Windows Store apps tiles, but don't confuse them—they are not interchangeable. This topic walks you through the creation of the following example file, in which the Square150x150Logo and Square70x70Logo attributes are optional, but all others are required.


<Application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <VisualElements
        BackgroundColor="#FF0000"
        ShowNameOnSquare150x150Logo="on"
        ForegroundText="light"
        Square150x150Logo="Assets\150x150Logo.png"
        Square70x70Logo="Assets\70x70Logo.png"/>
</Application>

Prerequisites

  • An understanding of XML
  • An understanding of command-line parameters
  • An understanding of resource naming and packaging for image scaling, high-contrast, and localized versions. For more information, see How to name resources using qualifiers.

Instructions

Step 1: Create the customization XML file

  • Specifies customizations for your tile
  • Place in the same directory as your executable file
  • Give the same name as your executable file, with an extension of ".VisualElementsManifest.xml". For example, for the executable file "contoso.exe", the accompanying XML file is named "contoso.visualelementsmanifest.xml".

Add the following code to the XML file you've created.


<Application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <VisualElements/>
</Application>

Step 2: Declare a background color

  • Required
  • Specify as any RGB hexadecimal value or one of these predefined strings:
    • black
    • silver
    • gray
    • white
    • maroon
    • red
    • purple
    • fuchsia
    • green
    • lime
    • olive
    • yellow
    • navy
    • blue
    • teal
    • aqua

Examples of both ways to express the color value are shown here:


<Application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <VisualElements
        BackgroundColor="#FF0000"/>
</Application>


<Application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <VisualElements
        BackgroundColor="red"/>
</Application>

Step 3: Declare whether to show the app's name on the tile

  • Required
  • The ShowNameOnSquare150x150Logo attribute has two possible values:
    • "on" to show the name
    • "off" to hide the name
  • Only the medium (150x150) tile size can display an app name.

The app name is the name of the app's Start menu shortcut file, or its executable file if no shortcut file exists.


<Application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <VisualElements
        BackgroundColor="#FF0000"
        ShowNameOnSquare150x150Logo="on"/>
</Application>

Step 4: Declare a foreground text color

  • Required, even when ShowNameOnSquare150x150Logo="off"
  • Refers to the app's name on the tile.
  • The ForegroundText attribute has two possible values:
    • "light" for a white text
    • "dark" for a black text

Choose a value that shows best against your declared background color. For maximum visibility and accessibility, aim for at least a 4.5-to-1 luminance ratio between the text color and the background color. For more information, see the W3C accessibility standard G18: Ensuring that a contrast ratio of at least 4.5:1 exists between text (and images of text) and background behind the text.


<Application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <VisualElements
        BackgroundColor="#FF0000"
        ShowNameOnSquare150x150Logo="on"
        ForegroundText="light"/>
</Application>

Step 5: Specify images

  • Optional
  • Supply full-bleed images to replace the default icon and background
  • Only medium (150x150) and small (70x70) tile sizes supported
  • Normal tile image restrictions apply:
    • Dimensions less than or equal to 1024x1024 pixels
    • File size of less than or equal to 200 KB
    • File type .png, .jpg, .jpeg, or .gif

Important  If you opt for a custom image, you must specify an image for both the Square150x150Logo and Square70x70Logo attributes. If you specify only one of those attributes, this entire XML file is ignored and the default styling (app icon and background) is applied to the tile.

 

Tile design best practices specify that if your tile is not a live tile, it should not claim the extra screen space required for wide (310x150) and large (310x310) tiles. Because a desktop app's tile is always static and never live, those additional tile sizes are not supported in this schema.

In this example, the images are located in a folder named "Assets", which is a sibling of the YourAppName.VisualElementsManifest.xml file. These file names can be either the true file names or generic names used for the scaled, high-contrast, or localized files discussed in step 6. See the Remarks section for a discussion of image asset naming.


<Application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <VisualElements
        BackgroundColor="#FF0000"
        ShowNameOnSquare150x150Logo="on"
        ForegroundText="light"
        Square150x150Logo="Assets\150x150Logo.png"
        Square70x70Logo="Assets\70x70Logo.png"/>
</Application>

This is now your complete .VisualElementsManifest.xml. Include this file in your app's installation as a sibling of your app's executable file.

Step 6: Specify images for scaling, localization, and high contrast

  • Optional, but recommended
  • If you do not provide scaled, high-contrast, or localized images, you can skip this step
  • For maximum display quality, provide a full set of scaled assets for each image specified in step 5. See the Remarks section for more details.
  • Use normal resource management system naming conventions and Resource.pri file

Note  If you do not provide a full set of scaled assets, Windows scales the asset or assets that you do include as necessary. Including one of the larger sizes (140% or 180%) is best, because scaling down normally gives better results than scaling up.

 

Based on the system settings active when the tile is updated, Windows uses a Resources.pri file to choose the right image asset from your set. We'll create that file in this step.

  1. Create a working folder. This folder isn't included in your app's installation, it's just used during the creation of the Resources.pri file. In this example, we call it "CreateResources".

    md %USERPROFILE%\Documents\CreateResources

  2. Create a subdirectory of CreateResources to hold your image files. In this example, we call it "Assets".

    md %USERPROFILE%\Documents\CreateResources\Assets

  3. Place your scaled, high-contrast, and/or localized images in the "Assets" folder. You can include your images as a flat list or structured in subdirectories, as long as you follow the required naming and structure conventions. For the purposes of this example, we'll provide the following scaled and high-contrast assets as a flat list.

    • 150x150Logo.scale-80.png
    • 150x150Logo.scale-100.png
    • 150x150Logo.scale-140.png
    • 150x150Logo.scale-180.png
    • 70x70Logo.scale-80.png
    • 70x70Logo.scale-100.png
    • 70x70Logo.scale-140.png
    • 70x70Logo.scale-180.png
    • 150x150Logo.scale-80_contrast-white.png
    • 150x150Logo.scale-100_contrast-white.png
    • 150x150Logo.scale-140_contrast-white.png
    • 150x150Logo.scale-180_contrast-white.png
    • 150x150Logo.scale-80_contrast-black.png
    • 150x150Logo.scale-100_contrast-black.png
    • 150x150Logo.scale-140_contrast-black.png
    • 150x150Logo.scale-180_contrast-black.png
    • 70x70Logo.scale-80_contrast-white.png
    • 70x70Logo.scale-100_contrast-white.png
    • 70x70Logo.scale-140_contrast-white.png
    • 70x70Logo.scale-180_contrast-white.png
    • 70x70Logo.scale-80_contrast-black.png
    • 70x70Logo.scale-100_contrast-black.png
    • 70x70Logo.scale-140_contrast-black.png
    • 70x70Logo.scale-180_contrast-black.png

  4. Create a MakePRI configuration file. This is an XML file used by MakePRI.exe to specify which images are indexed in Resources.pri. Run the following command to create the configuration file, which we name "TestAppConfig.xml". Notice that we're not writing that file to our CreateResources folder. This prevents the configuration file itself from being included in the index.

    Important  The MakePRI.exe command-line tool is included in the Windows SDK, downloadable free of charge. If you use Microsoft Visual Studio, MakePRI.exe is probably already on your system as part of that installation.

     

    This command and the next assume that the location of MakePRI.exe is in your path. If it is not, search for it under "Program Files\Windows Kits" and include its full path in these commands.

    
makepri createconfig /cf %USERPROFILE%\Documents\TestAppConfig.xml /dq lang-en-US_scale-100_contrast-high
    Command argument Definition
    /cf Path and name of the configuration file you're creating
    /dq The default qualifier(s). At least one qualifier (lang, scale, etc.) is required.

     

  5. Create the Resources.pri file. Run the following command, which uses the TestAppConfig.xml configuration file you've just created to produce a Resources.pri file in the CreateResources directory.

    
makepri new /pr %USERPROFILE%\Documents\CreateResources /cf %USERPROFILE%\Documents\TestAppConfig.xml /in TestApp /of %USERPROFILE%\Documents\CreateResources\Resources.pri
    Command argument Definition
    /pr Root location of project files
    /cf Path of the configuration XML file
    /in Name for the index of resources within the Resources.pri file. Typically matches the app's name.
    /of Output location of the Resources.pri file. If omitted, the project root specified with the /pr argument is used.

     

  6. Include the Resources.pri file in your app's installation. Place it in the same directory as the app's .exe file and its .VisualElementsManifest.xml file. During installation, put the .VisualElementsManifest.xml in place before you install the app's shortcut file.

Step 7: Important! Refresh your shortcut file

If your app is already installed, you must nudge your shortcut after the new or updated .VisualElementsManifest.xml is in place or it will be ignored. The following Windows PowerShell command example for the fictional Contoso app is one model for how to accomplish this, although there are many ways that it can be done.


(ls "$env:programdata\microsoft\windows\start menu\programs\contoso.lnk").lastwritetime = get-date

Remarks

Important  If anything is wrong with your .VisualElementsManifest.xml file, the tile reverts to the Windows-supplied default. Potential file errors can include an invalid XML file, the omission of required attributes, invalid attribute values, or images that can't be located.

 

You can use the MakePRI.exe file with the dump command option to examine the contents of the Resources.pri file. This can be useful for troubleshooting. For more information on the MakePRI.exe tool, see MakePRI.exe configuration and MakePRI.exe command options.

When troubleshooting, you can also examine the Event Viewer for the 28032 event in the Application and Services Logs\Microsoft\Windows\Shell-Core\Operational log. The event details data includes the path of the .VisualElementsManifest.xml file, the HRESULT error code, and an error string, if one is available.

Working with the resource management system

While it is beyond the scope of this topic to fully explain the details of the resource management system, we'll give a brief overview here. For an in-depth discussion, read the Resource Management System topics.

A full set of resource images includes the following:

  • A separate image for each DPI scaling plateau (80%, 100%, 140%, and 180%)
  • High-contrast versions (white on black and black on white) of each image
  • Localized images if you want your tile to use a different image based on the system language, such as when your image contains text

You can supply all of those images or just a subset.

Your file names will follow the pattern name.scale-100.ext, name.scale-100_contrast-black.ext, and so on. You can also provide qualifiers through a directory structure rather than in the file name. However, in your .VisualElementsManifest.xml file, you refer only to the root name of the file. For instance, you might provide these files for the medium tile size:

  • 70x70Logo.scale-80.png
  • 70x70Logo.scale-100.png
  • 70x70Logo.scale-140.png
  • 70x70Logo.scale-180.png
  • 70x70Logo.scale-80_contrast-white.png
  • 70x70Logo.scale-100_contrast-white.png
  • 70x70Logo.scale-140_contrast-white.png
  • 70x70Logo.scale-180_contrast-white.png
  • 70x70Logo.scale-80_contrast-black.png
  • 70x70Logo.scale-100_contrast-black.png
  • 70x70Logo.scale-140_contrast-black.png
  • 70x70Logo.scale-180_contrast-black.png

However, in your .VisualElementsManifest.xml file, you only refer to "70x70Logo.png" as in our example. Based on the current system settings, Windows uses the Resources.pri file to select the correct version of the 70x70Logo file from all of those listed options. For a full tutorial on the naming conventions that make this system work, see Quickstart: Using file or image resources.

The desktop app tile customization XSD

The XSD for the schema used in the customization of tiles for desktop apps is shown here.


<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"  
           xmlns:xs="http://www.w3.org/2001/XMLSchema">  
  
    <xs:simpleType name="st_nonemptystring">  
        <xs:restriction base="xs:string">  
            <xs:minLength value="1"/>  
            <xs:maxLength value="32767"/>  
            <xs:pattern value="[^\s]|([^\s].*[^\s])"/>  
        </xs:restriction>  
    </xs:simpleType>  
    
    <xs:simpleType name="st_filenamecharset">  
        <xs:restriction base="st_nonemptystring">  
            <xs:pattern value=&quot;[^&lt;&gt;&quot;:%\|\?\*]+&quot;/>  
        </xs:restriction>  
    </xs:simpleType>  
  
    <xs:simpleType name="st_filename">  
        <xs:restriction base="st_filenamecharset">  
            <xs:pattern value="([^/\\]*[^./\\]+)(\\[^/\\]*[^./\\]+)*"/>  
            <xs:pattern value="([^/\\]*[^./\\]+)(/[^/\\]*[^./\\]+)*"/>  
            <xs:maxLength value="256"/>  
        </xs:restriction>  
    </xs:simpleType>  
  
    <xs:simpleType name="st_imagefile">  
        <xs:restriction base="st_filename">  
            <xs:pattern value=".+\.((jpg)|(png)|(jpeg)|(gif))"/>  
        </xs:restriction>  
    </xs:simpleType>  
  
    <xs:simpleType name="st_color">  
        <xs:restriction base="xs:string">  
            <xs:pattern value="#[\da-fA-F]{6}"/>  
            <xs:pattern value="black|silver|gray|white|maroon|red|purple|fuchsia|green|lime|olive|yellow|navy|blue|teal|aqua"/>  
        </xs:restriction>  
    </xs:simpleType>  
  
    <xs:simpleType name="st_foregroundtext">  
        <xs:restriction base="xs:string">  
            <xs:enumeration value="light"/>  
            <xs:enumeration value="dark"/>  
        </xs:restriction>  
    </xs:simpleType>  

    <xs:simpleType name="st_showname">
        <xs:restriction base="xs:string">
            <xs:enumeration value="on"/>
            <xs:enumeration value="off"/>
        </xs:restriction>
    </xs:simpleType>
  
    <xs:complexType name="ct_visualelements">
        <xs:attribute name="Square150x150Logo" type="st_imagefile" use="optional"/>  
        <xs:attribute name="Square70x70Logo" type="st_imagefile" use="optional"/>
        <xs:attribute name="ForegroundText" type="st_foregroundtext" use="required"/>  
        <xs:attribute name="BackgroundColor" type="st_color" use="required"/>
        <xs:attribute name="ShowNameOnSquare150x150Logo" type="st_showname" use="required"/>  
    </xs:complexType>  
  
    <xs:complexType name="ct_application">  
        <xs:all>  
            <xs:element name="VisualElements" type="ct_visualelements" />  
        </xs:all>  
    </xs:complexType>  
  
    <xs:element name="Application" type="ct_application" />  
  
</xs:schema>

Resource Management System

Quickstart: Using file or image resources

How to name resources using qualifiers

MakePRI.exe configuration

MakePRI.exe command options