Edit

Make custom CSS files themable in SharePoint

  • Article

Learn how to add comment-style markup to a CSS file so that it can be used in the SharePoint theming engine.

Introduction to annotations

Annotations are special comment-style markup that tell the SharePoint theming engine how to theme properties in a CSS file. When a theme is applied to a site, the theming engine replaces the CSS property values with the appropriate theme values. In SharePoint, you can use annotations to change the color, font, or background image. You can also recolor an image. If you are using custom CSS files, you must add these annotations to the CSS files if you want to use them with the SharePoint theming engine. If you apply a theme to a site that uses custom CSS files, and you haven't added annotations, the CSS properties remain unchanged. This can result in a site that has a mismatched design.

This article describes the available annotations and how to register CSS files.

For more information about custom themes, see How to: Deploy a custom theme in SharePoint and How to: Create a master page preview file in SharePoint.

Add annotations to custom CSS files

Annotations tell the SharePoint theming engine how to theme properties in a CSS file. This section describes the available annotations and how they can be used.

ReplaceColor annotation

The ReplaceColor annotation replaces the color value with the specified theme color. It can be used with CSS properties that define a color value, such as color, background-color, border, and so on.

The following shows the format for the ReplaceColor annotation.

/* [ReplaceColor(themeColor:"ColorSlot"[, themeShade:"ShadeValue"][, themeTint:"TintValue"][, opacity:"OpacityValue"])] */

Replace ColorSlot with the annotation name of the color slot to use. To see a list of available color slots, see the Color slot mapping section in Color palettes and fonts in SharePoint.

Use the optional themeShade parameter if you want to darken the theme color. Replace ShadeValue with a numeric value from 0.0 (no change) to 1.0 (darkest).

Use the optional themeTint parameter if you want to lighten the theme color. Replace TintValue with a numeric value from 0.0 (no change) to 1.0 (lightest).

Use the optional opacity parameter if you want to specify the opacity of the theme color. Replace OpacityValue with a numeric value that specifies the opacity setting. The opacity setting ranges from 0.0 (fully transparent) to 1.0 (fully opaque).

The following shows examples of the ReplaceColor annotation being used in a CSS file.

  • /* [ReplaceColor(themeColor:"BodyText")] */ color:#444;
  • /* [ReplaceColor(themeColor:"BackgroundOverlay",opacity:"0.5")] */ background-color:#fff;
  • /* [ReplaceColor(themeColor:"EmphasisBackground",themeTint:"0.05")] */ background-color:#f2faff;

ReplaceFont annotation

The ReplaceFont annotation adds the specified theme font to the list of available fonts. It can be used with the font and font-family CSS properties.

The following shows the format for the ReplaceFont annotation.

/* [ReplaceFont(themeFont:"FontSlot")] */

Replace FontSlot with the name of the font slot to use. To see a list of available font slots, see the Font slots section in Color palettes and fonts in SharePoint.

The following shows an example of the ReplaceFont annotation. In this example, if the body font slot is defined as Courier in the theme, Courier will be added as the first item in the list of available fonts in the Choose the Look wizard.

  • /* [ReplaceFont(themeFont:"body")] */ font-family:"Segoe UI","Segoe",Tahoma,Helvetica,Arial,sans-serif;

ReplaceBGImage annotation

The ReplaceBGImage annotation replaces the background image in the CSS file with the theme background image. It can be used with the background and background-image CSS properties.

The following shows the format for the ReplaceBGImage annotation. The ReplaceBGImage annotation can also be used with the AlphaImageLoader filter to support earlier versions of Internet Explorer.

/* [ReplaceBGImage] */

RecolorImage annotation

The RecolorImage annotation recolors the image specified.

The following describes the format of the RecolorImage annotation.

/* [RecolorImage(themeColor:"ColorSlot"[, method:["Tinting"|"Blending"|"Filling"]][, includeRectangle: {x:x-Setting,y:y-Setting,width:RegionWidth,height:RegionHeight})] */

Replace ColorSlot with the annotation name of the color slot. To see a list of available color slots, see the Color slot mapping section in Color palettes and fonts in SharePoint.

Use the optional method parameter if you want to specify the recoloring method.

Use the optional includeRectangle parameter if you want to recolor only a specific region of an image. Replace x-Setting, y-Setting, RegionWidth, and RegionHeight with the x-coordinate, y-coordinate, width, and height of the region that you want to recolor.

The following shows examples of the RecolorImage annotation being used in a CSS file.

  • /* [RecolorImage(themeColor:"SubtleBodyText",method:"Tinting")] */ background-image:url("/_layouts/15/images/tabtitlerowbottombg.png?rev=23");
  • /* [RecolorImage(themeColor:"BodyText",method:"Filling",includeRectangle:{x:161,y:178,width:16;height:16})] */ background:url("/_layouts/15/images/spcommon.png?rev=23") no-repeat -161px -178px;

Upload the CSS file to the Themable folder in the Style library

Place the custom CSS files in the Themable folder in the Style library (not the Themable folder in the Master Page Gallery). Only CSS files that are stored in the Themable folder in the Style library are recognized by the theming engine. The Themable folder is created automatically for publishing sites. Otherwise, you can create the Themable folder in the correct location (http:// SiteCollectionName/Style Library/ language/Themable/).

Note

The name of the language folder must be in the 4-digit format ll-cc to identify the language and culture, respectively. For example, en-us or ar-sa. For more information, see Language identifiers and OptionState Id values in Office 2013.

CSS files must be checked in and published. If CSS files are changed, you must reapply the theme for the changes to be recognized.

Register the CSS file

You must register the CSS file with a master page before the CSS file can be used by the theming engine. This directs the master page to the CSS file when you apply a theme to a site. To register a CSS file, you add a <SharePoint:CssRegistration> element to the <head> element of the master page. The following shows the format of the <SharePoint:CssRegistration> element.

<SharePoint:CssRegistration Name="CSSFileLocation" runat="server" />

Replace CSSFileLocation with the location of the CSS file.

The following is an example of an <SharePoint:CssRegistration> element.

<head>
…
<SharePoint:CssRegistration Name="<%$SPUrl:~SiteCollection/Style Library/~language/Themable/MyCustomFile.css%>" runat="server" />
</head>

Note

The %$SPUrl token cannot be used on SharePoint Foundation 2013. You must use a URL to specify the location of the CSS file.

See also