SharePoint site theming: CSOM development

The SharePoint client-side object model (CSOM) provides access to the SharePoint object model from code that is running locally or on a different server than SharePoint.

Prerequisites

Before you get started, make sure that you're familiar with the following:

You also need to reference the Microsoft.SharePointOnline.CSOM NuGet package (version 16.0.27011.12008 or later).

CSOM code example

The following example shows how to create a Microsoft.Online.SharePoint.TenantAdministration.Tenant object and call the GetAllGlobalThemes method to return a list of themes.

Note

The URL used to create the context object includes the -admin suffix because TenantAdministration methods work with the admin site.
Create a Tenant instance with the Tenant constructor, and then call the methods on that instance.
You can use the same approach to call other theme management methods.

using System.Security;
using Microsoft.SharePoint.Client;
using Microsoft.Online.SharePoint.TenantAdministration;
using Microsoft.Online.SharePoint.TenantManagement;

...

ClientContext ctx = new ClientContext("https://mysite-admin.sharepoint.com/");
var pwd = "mypassword";
var passWord = new SecureString();
foreach (char c in pwd.ToCharArray()) passWord.AppendChar(c);
ctx.Credentials = new SharePointOnlineCredentials("admin@mydomain.com", passWord);
Tenant tenant = new Tenant(ctx);
ClientObjectList<ThemeProperties> themes = tenant.GetAllGlobalThemes();

Theme definition example

For methods that take a theme argument, the following code defines an SPOTheme class that you can use to create custom themes. For the new theme format, only the Name and ColorPairs properties are required. For the legacy theme format, the Name, Palette, and IsInverted properties are required.

/// <summary> 
/// Properties defining a theme in SharePoint Online. 
/// </summary> 
public class SPOTheme 
{ 
    /// <summary> 
    /// Specifies the name of the theme. This must uniquely identify the theme. 
    /// </summary> 
    public string Name 
    { 
        get; private set; 
    } 
    /// <summary> 
    /// Specifies the palette of colors in the theme, as a dictionary of theme slot values. 
    /// </summary> 
    public IDictionary<String, String> Palette 
    { 
        get; private set; 
    } 
    /// <summary> 
    /// Specifies the color pairs setting of the theme.
    /// </summary> 
    public IDictionary<string, IList<Dictionary<string, string>>> ColorPairs
    { 
        get; private set; 
    } 
    /// <summary> 
    /// Specifies whether the theme is inverted, with a dark background and a light foreground. 
    /// </summary> 
    public bool IsInverted 
    { 
        get; private set; 
    } 
}

Applying a theme

There's currently no supported CSOM API to programmatically apply a theme to a specific site. For information on applying custom themes to individual site collections see SharePoint site design and site script overview

Methods/properties of the Microsoft.Online.SharePoint.TenantAdministration.Tenant class

Use the following methods to customize the set of available themes for a SharePoint tenant administration site. You can add a new custom theme, update an existing theme, or delete a theme, and you can retrieve a specific theme or all themes. You can also hide or restore the default themes that come with SharePoint.

AddTenantThemeAdvanced public method

Add a theme to the organization.

In multi-geo environments, themes added by an administrator in the primary geography are automatically propagated and available across the organization. This method is not supported for administrators in satellite geographies.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name, string themeJson, bool shouldParseColorPair
Return type: ClientResult<bool>

UpdateTenantThemeAdvanced public method

Update the settings for an existing theme.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name, string themeJson, bool shouldParseColorPair
Return type: ClientResult<bool>

AddTenantTheme public method

Add a theme to the organization. This method is not supported for administrators in satellite geographies.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name, string themeJson
Return type: ClientResult<bool>

UpdateTenantTheme public method

Update the settings for an existing theme.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name, string themeJson
Return type: ClientResult<bool>

DeleteTenantTheme public method

Delete a theme from the tenant.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name
Return type: void

GetAllGlobalThemes public method

Retrieve the complete set of custom themes defined at the tenant level, including themes created through command-based tools and those created in the Brand Center UI.

Note

To support consistent branding and simplify governance, theme management is transitioning to a centralized model.

The primary geo will act as the central location for organization-wide theme creation and management. Themes created here will be visible and applicable across satellite geos.
The satellite Geo Administrators will be able to view themes from the primary geo to their own sites by using GetAllGlobalThemes method. Themes previously created within satellite geos will remain available for use. However, creating new themes in satellite geos will no longer be supported going forward.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: none
Return type: ClientObjectList<ThemeProperties>

GetAllTenantThemes public method

Retrieve all the custom themes that are created on current tenant through command-based tools.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: none
Return type: ClientObjectList<ThemeProperties>

GetGlobalTheme public method

Retrieve a theme by name, including themes created through command-based tools and those created in the Brand Center UI.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Parameters: string name
Return type: ThemeProperties

GetTenantTheme public method

Retrieve a theme by name.