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.1.6906.1200 or later).

CSOM code example

The following example shows how to create a Microsoft.Online.SharePoint.TenantAdministration.Tenant object and call the GetAllTenantThemes 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.GetAllTenantThemes();

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.

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

AddTenantTheme public method

Add a theme to the tenant.

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

DeleteTenantTheme public method

Delete a theme from the tenant.

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

GetAllTenantThemes public method

Retrieve all the themes that are currently available in the tenant, including any custom themes that have been added. Default themes are only included if the HideDefaultThemes property is false (the default value).

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

GetTenantTheme public method

Retrieve a theme by name.

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

HideDefaultThemes public property

This property indicates whether the default themes are available in the theme picker UI. The default setting is false (the default themes are available), but you might want to set this property to true after you define custom themes, to allow only specific themes to be used.

Namespace: Microsoft.Online.SharePoint.TenantAdministration.Tenant
Type: Boolean

UpdateTenantTheme public method

Update the settings for an existing theme.

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

Methods of the Microsoft.Online.SharePoint.TenantManagement.Tenant class

These are alternative APIs to manage your themes at the tenant level.

AddTenantTheme public method

Add a theme to the tenant.

Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: string name, string themeJson
Return type: ClientResult

GetAllTenantThemes public method

Retrieve all the themes that are currently available in the tenant, including any custom themes that have been added. Default themes are only included if the HideDefaultThemes property is false (the default value).

Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: none
Return type: ClientObjectList

GetHideDefaultThemes public method

Read the current setting for whether to hide default themes in the theme picker UI.

Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: none
Return type: ClientResult

GetTenantTheme public method

Retrieve a theme by name.

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

SetHideDefaultThemes public method

Specify whether to hide default themes in the theme picker UI.

Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: Boolean
Return type: void

UpdateTenantTheme public method

Update the settings for an existing theme.

Namespace: Microsoft.Online.SharePoint.TenantManagement.Tenant
Parameters: string name, string themeJson
Return type: ClientResult

See also