Themable custom master page in SharePoint 2010

Once you understand how theme colors work in SharePoint 2010, you’re on your way to creating your own themable (or “themeable”) master pages!

This article is not going to go through the details of making your own master page, as there are plenty of resources on creating custom master pages in SharePoint 2010. Instead, I’ll cover what you need to know to successfully create a themable master page.

I’m going to start with my own custom master page design – here’s what it looks like:

1. Ensure graphics can be recolored appropriately.

The top header area has a wrapper div with an orange background color (#ffbe18). Inside the wrapper div, my menu div uses a white background color, but I have a transparent background PNG called “navtab.png,” positioned on the right side of the div so that there is a curved tab effect.

When a new theme is applied, SharePoint’s theming engine can recolor everything. The wrapper div’s background color can change (orange to green), the menu div’s background color can change (white to beige), and the non-transparent pixels in the graphic are recolored from orange to green as well.

So – for any images that you want to use as part of your theme, you’ll want to make sure that recoloring them will work as you want. For example, you would not want to use an image such as the one shown below, because there are different hues in the same graphic, so recoloring would not produce the desired effect. (Keep reading below about how recoloring images works so that you know exactly what you can do!)

By the way – any graphics that you want to be recolored must be in PNG format.

2. Set up your CSS without shorthand notations for colors and backgrounds.

Instead of writing your CSS like this:

#cc-topmenu {
background: #fff url('navtab.png') no-repeat top right;
margin-right: 250px;
height: 30px;
padding-left: 10px;

Write your CSS so that the background properties are separated:

#cc-topmenu {
background-color: #fff;
background-image: url('navtab.png');
background-repeat: no-repeat;
background-position: top right;
margin-right: 250px;
height: 30px;
padding-left: 10px;

3. Add in theme tokens

Now, add in theme comments — that is, theme “tokens.” You can replace colors (font colors, background colors, border colors) with the ReplaceColor token.

/* [ReplaceColor(themeColor:"COLOR")] */

Color: Dark1, Dark2, Light1, Light2, Accent1, Accent2, Accent3, Accent4, Accent5, Accent6, Hyperlink, FollowedHyperlink. You can also append -Lightest, -Lighter, -Medium, -Darker, -Darkest to get the various shades of each color. (For example — Light1-Medium will give you the “medium” shade of your Light 1 color from your theme.)

You can get even more variations by using the themeShade (darkening) or themeTint (lightening) properties, if one of the previous “Lightest… Darkest” shortcut properties don’t work for you.

/* [ReplaceColor(themeColor:"COLOR", themeShade:"VALUE")] */
/* [ReplaceColor(themeColor:"COLOR", themeTint:"VALUE")] */

Value: Decimal value from 1.0 (no change from the color) to 0.0 (extremely dark or extremely light). See the diagram below for how themeTint and themeShade values affect the accent color, which is orange. (This may require some experimentation on your part to get the desired color!)

The RecolorImage token uses the same color options, but you can apply the color options in a few different ways:

  • Tinting: Change the hues of the graphic to your color – this is the default
    /* [RecolorImage(themeColor:"Accent1")] */


    /* [RecolorImage(themeColor:"Accent1"),method:"Tinting"] */
  • Blending: Mix your color with the original hues of the graphic
    /* [RecolorImage(themeColor:"Accent1",method:"Blending")] */
  • Filling: Completely replace all non-transparent pixels with the color
    /* [RecolorImage(themeColor:"Accent1",method:"Filling")] */

You can also recolor just a portion of an image by specifying a rectangular area with the “includeRectangle” property. The x and y values determine the upper left point of the rectangle, and then you specify the width and height of the rectangle to recolor.

/* [RecolorImage(themeColor:"Accent1-Lighter",method:"Filling",includeRectangle:{x:0,y:0,width:100,height:30})] */

Note that if you refer to the image multiple times in the CSS, the last reference to the image is what it will look like. The theming engine only creates one recolored version of the image, so it will choose whichever definition overrides the others.

Here’s what my CSS looks like after adding in the theme tokens (I’ve stripped out my layout code so that you can just see the colors):

body #s4-ribbonrow { /* recoloring the ribbon, originally black */
/* [ReplaceColor(themeColor:"Dark1")] */background-color: #000;
#s4-workspace { /* recoloring the main background, originally grey */
/* [ReplaceColor(themeColor:"Light1-Lightest")] */background-color: #eeeeee;
#cc-wrapper {
margin: 0 20px; /* recoloring the content area, originally white */
/* [ReplaceColor(themeColor:"Light1")] */background-color: #ffffff;
#cc-header {  /* recoloring the header, originally orange */
/* [ReplaceColor(themeColor:"Accent1")] */background-color: #ffbe18;
#cc-topmenu { /* recoloring the menu, originally white, and recoloring the right curved tab graphic, originally orange */
/* [ReplaceColor(themeColor:"Light1")] */background-color: #fff;
/* [RecolorImage(themeColor:"Accent1")] */background-image: url('navtab.png');
background-repeat: no-repeat;
background-position: top right;
#cc-left { /* recoloring the gradient background image behind the left column, originally green */
/* [RecolorImage(themeColor:"Accent2-Lightest")] */background-image: url('leftbg.png');
.s4-ql ul.root > li > .menu-item, .s4-qlheader, .s4-qlheader:visited { /* recoloring the navigation headers */
/* [ReplaceColor(themeColor:"Accent2-Darker")] */color: #3e750e;
.s4-ql ul.root ul > li > a { /* recoloring the navigation links */
/* [ReplaceColor(themeColor:"Dark1")] */color: #000;
#cc-breadcrumbs { /* recoloring the breadcrumb navigation */
/* [ReplaceColor(themeColor:"Accent2")] */color: #82c942;
.ms-rteElement-H1B { /* recoloring the heading font */
/* [ReplaceColor(themeColor:"Accent1")] */color: #ffbe18;
.ms-rteElement-P { /* recoloring paragraph font */
/* [ReplaceColor(themeColor:"Dark1-Medium")] */color: #666;

Important note: Everything is case-sensitive!! So “Dark1-medium” won’t work. You MUST put “Dark1-Medium.”

4. Put your CSS in a Themable folder

Your CSS (and image) files should go in the top level of your site collection into either /Style Library/Themable or /Style Library/~language-code/Themable (such as /Style Library/en-us/Themable). The Themable folder is created automatically for publishing sites; if you don’t see it in the Style Library folder, you can just create your own folder. Just be sure to spell it properly! You can then drop in your styles and images into those folders, or into a subfolder if, like me, you want things to be somewhat organized.

5. Use <SharePoint:CssRegistration> to link your stylesheet

In your master page, you’ll have to use <SharePoint:CssRegistration> to link your stylesheet, like this:

<SharePoint:CssRegistration name="<% $SPUrl:~sitecollection/<em>location-of-stylesheet</em> %>" After="corev4.css" runat="server"/>

Here’s the example from my master page:

<SharePoint:CssRegistration name="<% $SPUrl:~sitecollection/Style%20Library/Themable/corriecustom/styles.css%>" After="corev4.css" runat="server"/>

6. Check and publish and change your theme

I tend to refresh often as I’m working on a custom master page design. If you’re trying to see how your themable changes affect your design, be sure to check in and publish your stylesheet and images. You will then need to apply a new theme so that SharePoint regenerates the themed files. Then, you’ll be able to see your changes! Below, you can see my site with my custom master page applied, after switching themes a few times!

Cay theme applied

Grapello theme applied

Resources and links

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s