In this article

Make custom CSS files themable in SharePoint

09/25/2017

5 minutes to read

Contributors

In this 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.

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.

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.

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.

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/).

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 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.