SharePoint site theming: PowerShell cmdlets

SharePoint tenant administrators can use PowerShell cmdlets to create, retrieve, and remove site themes. Developers can also use the SharePoint REST API to handle theme management tasks.

For information about how themes are defined and stored, see JSON schema reference.

Getting started

To run the PowerShell cmdlets for theme management, you'll need to do the following:

  1. Download and install the SharePoint Online Management Shell. If you already have a previous version of the shell installed, uninstall it first and then install the latest version.
  2. Follow the instructions at Connect to SharePoint Online PowerShell to connect to your SharePoint tenant.

To verify your setup, try using the Get-HideDefaultThemes cmdlet to read the HideDefaultThemes setting. If the cmdlet runs and returns False with no errors, as shown in the following example, you're ready to proceed.

c:\> Get-HideDefaultThemes
False

Site theme cmdlets

The following cmdlets are available for managing site themes from PowerShell:

  • Add-SPOTheme — Creates a new custom theme, or overwrites an existing theme to modify its settings.
  • Get-SPOTheme — Retrieves settings for an existing theme.
  • Remove-SPOTheme — Removes a theme from the theme gallery.
  • Set-HideDefaultThemes — Specifies whether the default themes should be available.
  • Get-HideDefaultThemes — Queries the current HideDefaultThemes setting.

Add-SPOTheme

The Add-SPOTheme cmdlet creates a new theme or updates an existing theme. The color pallette settings are passed as a dictionary.

In the following example, a new theme named "Custom Cyan" is created, with color pallette settings that are various shades of cyan. Note that this example uses a HashToDictionary function to convert a hash table created with the @{} notation into a dictionary, as required by Add-SPOTheme.

function HashToDictionary {
  Param ([Hashtable]$ht)
  $dictionary = New-Object "System.Collections.Generic.Dictionary``2[System.String,System.String]"
  foreach ($entry in $ht.GetEnumerator()) {
    $dictionary.Add($entry.Name, $entry.Value)
  }
  return $dictionary
}

$themepallette = HashToDictionary(
 @{
  "themePrimary" = "#00ffff";
  "themeLighterAlt" = "#f3fcfc";
  "themeLighter" = "#daffff";
  "themeLight" = "#affefe";
  "themeTertiary" = "#76ffff";
  "themeSecondary" = "#39ffff";
  "themeDarkAlt" = "#00c4c4";
  "themeDark" = "#009090";
  "themeDarker" = "#005252";
  "neutralLighterAlt" = "#f8f8f8";
  "neutralLighter" = "#f4f4f4";
  "neutralLight" = "#eaeaea";
  "neutralQuaternaryAlt" = "#dadada";
  "neutralQuaternary" = "#d0d0d0";
  "neutralTertiaryAlt" = "#c8c8c8";
  "neutralTertiary" = "#a6a6a6";
  "neutralSecondaryAlt" = "#767676";
  "neutralSecondary" = "#666666";
  "neutralPrimary" = "#333";
  "neutralPrimaryAlt" = "#3c3c3c";
  "neutralDark" = "#212121";
  "black" = "#000000";
  "white" = "#fff";
  "primaryBackground" = "#fff";
  "primaryText" = "#333"
 }
)

Add-SPOTheme -Name "Custom Cyan" -Palette $themepallette -IsInverted $false

If you want to update an existing theme (to modify some of its color settings, for example), use the same syntax as shown previously but add the -Overwrite flag to the Add-SPOTheme cmdlet.

Add-SPOTheme -Name "Custom Cyan" -Palette $themepallette -IsInverted $false -Overwrite

Adding a theme does not apply the theme to any sites. It adds the theme to your tenant store, and then the theme will be available in the list of themes under the Change the look option for modern pages.

Get-SPOTheme

The Get-SPOTheme cmdlet returns the settings for an existing theme. For example, here's how to use the Get-SPOTheme cmdlet to return the settings for the "Custom Cyan" theme created in the previous example.

C:\> Get-SPOTheme -Name "Custom Cyan" | ConvertTo-Json
{
    "Name":  "Custom Cyan",
    "Palette":  {
                    "themeLight":  "#affefe",
                    "themeTertiary":  "#76ffff",
                    "black":  "#000000",
                    "neutralSecondary":  "#666666",
                    "neutralTertiaryAlt":  "#c8c8c8",
                    "themeSecondary":  "#39ffff",
                    "themeDarker":  "#005252",
                    "primaryBackground":  "#fff",
                    "neutralQuaternary":  "#d0d0d0",
                    "neutralPrimaryAlt":  "#3c3c3c",
                    "neutralPrimary":  "#333",
                    "themeDark":  "#009090",
                    "themeLighter":  "#daffff",
                    "neutralTertiary":  "#a6a6a6",
                    "neutralQuaternaryAlt":  "#dadada",
                    "themeLighterAlt":  "#f3fcfc",
                    "white":  "#fff",
                    "neutralSecondaryAlt":  "#767676",
                    "neutralLighter":  "#f4f4f4",
                    "neutralLight":  "#eaeaea",
                    "neutralDark":  "#212121",
                    "themeDarkAlt":  "#00c4c4",
                    "neutralLighterAlt":  "#f8f8f8",
                    "primaryText":  "#333",
                    "themePrimary":  "#00ffff"
                },
    "IsInverted":  false
}

Note that this example uses the PowerShell ConvertTo-Json filter to display the theme in JSON format.

Remove-SPOTheme

The Remove-SPOTheme cmdlet removes a theme from your tenant store. For example, this cmdlet removes the "Custom Cyan" theme that was used in the previous examples.

c:\> Remove-SPOTheme -Name "Custom Cyan"

Set-HideDefaultThemes

NOTE: this cmdlet will be renamed to Set-SPOHideDefaultThemes in a future release, for consistency with other SharePoint PowerShell cmdlet.

The Set-HideDefaultThemes cmdlet is used to specify whether the default themes that come with SharePoint should be included in the theme picker list. For example, you might want to create custom themes for your sites and then remove the default themes, to ensure that all pages will use your custom themes.

Specify the setting as either $true to hide the default themes, or $false (the default setting) to allow use of the default themes. For example, this cmdlet hides the default themes.

Set-HideDefaultThemes $true

After creating the "Custom Cyan" theme, hiding the default themes will leave only the one custom theme in the themes list under Change the look.

To restore the default themes to the theme picker list, use the following cmdlet.

Set-HideDefaultThemes $false

Get-HideDefaultThemes

NOTE: this cmdlet will be renamed to Get-SPOHideDefaultThemes in a future release, for consistency with other SharePoint PowerShell cmdlets.

The Get-HideDefaultThemes cmdlet retrieves the currrent Set-HideDefaultThemes setting. You might want to use this cmdlet in a PowerShell script to read the setting and then take different actions based on whether the default themes are hidden. This cmdlet does not have any parameters.

c:\> Get-HideDefaultThemes
False

See also