Introduction of Site Design and Site Script in SharePoint Online

Published: Jun 24, 2019

Site Templates creation is one of the best feature provided by Microsoft in SharePoint sites to create new sites with similar structure for a better SharePoint development. However, it was not quite useful when you want to apply the same custom look and feel on multiple sites. For On-premise versions, there is a Feature Stapling which helps you to create same structure in site along with customized look and feel, and many other things. These site templates are not quite useful with Modern UI SharePoint sites in SharePoint Online. Also, they are not supported with new Team Site, Communication Site and Hub Site templates.

Microsoft has come up with new features called PnP Provisioning templates to provision the sites in SharePoint Online. It’s a very nice feature with vast abilities but requires more efforts even though you want very small number of configurations. Along with PnP Provisioning templates, Microsoft has introduced Site Design & Site Scripts to support custom configurations at less efforts than PnP Provisioning templates. Currently, Site Designs and Site Scripts are only supported by SharePoint Online.

What is Site Design?

Site Design is a pre-defined set of actions which can be used to create new sites with Modern UI in SharePoint Online. It will help you to have consistency across multiple site collections within same tenant. Using Site Design, you can for example, create new lists/libraries, site/list columns, content types, set themes, set site logo etc.

Site Design can be related to a template, but it’s not exactly a template attached with site. People get confused with template when they make changes in Site Design and expect that it would be applied to their existing site, but that’s not how Site Design work. To apply these changes in existing site, you will have to run Site Design in existing site.

For now, Microsoft has provided support for 2 templates with out of box Site Designs:

  • Communication site

Site design:  Topic, Showcase, Blank

  • Team site

Site design: Team site

You can see these templates during new site creation from new Modern UI SharePoint landing page. SharePoint landing page URL will be https://<tenant-name>/_layouts/15/sharepoint.aspx.

Communication Site

You can select Site Design while creating a new site from UI as shown above and you can apply Site Design to existing sites using REST, CSOM or PowerShell scripts. Site Designs are basically a package of scripts that runs in background when you select design to create a new site.

What is Site Script?

Site Scripts are JSON files, in which you can define ordered list of actions to be executed when Site Design is applied to an existing site or a new site is being created. Currently, UI is not available for Site Script. You must deal with Site Scripts using PowerShell only. Site Scripts can be run multiple times in same site.It has non-destructive nature that means it will add only missing elements to the site.

As of now, you can add below actions in your Site Script:

  1. Creating a new list or library (or altering the default one created with the site)
  2. Creating site columns, content types, and configuring other list settings
  3. Set site branding properties such as navigation layout, header layout and header background
  4. Applying a theme
  5. Setting a site logo
  6. Adding links to quick launch or hub navigation
  7. Triggering a Microsoft Flow
  8. Installing a deployed solution from the app catalog
  9. Set regional settings for the site
  10. Including principals (users and groups) to SharePoint roles
  11. Setting external sharing capability for the site

For complete set of actions along with JSON parameters, please check JSON Schema. You can copy-paste verbs in your JSON file from JSON Schema and you will just require changing parameter values. It’s a good practice to check out JSON schema regularly to get idea about new verbs. There is an 3rd party online tool – available to create a JSON code if you don’t want to create JSON by hand. Tools can be very handy to create complex Site Scripts.

Limitations of Site Script

Previously, 30 actions per Site Script was a limitation. This limitation will be remained for the scripts applied synchronously. But Microsoft has increased limit to 300 actions or 1,00,000 characters for the scripts applied asynchronously either through UI or commands. There is likewise a limit of 100 site scripts and 100 site designs per tenant.

Creating a new Site Design and Site Script

Let’s create a new Site Design and Site Script in tenant to get better idea.

Creating a Site Script in SharePoint Online

  • Create one JSON file with name “SiteScript.json” and place below code in it. In following code, 2 actions are defined, first will set theme in site and second will create new list in site.
  "$schema": "",
  "actions": [
      "verb": "applyTheme",	            //Theme will be set in site.
      "themeName": "Custom Cyan"                
      "verb": "createSPList",			//List will be created.
      "listName": "Students Information",       
      "templateType": 100,                      
      "subactions": [
          "verb": "SetDescription",
          "description": "List of Students."
          "verb": "addSPField",			//Column will be created.
          "fieldType": "Text",
          "displayName": "Full Name",
          "isRequired": true,
          "addToDefaultView": true
          "verb": "addSPField",
          "fieldType": "Number",
          "displayName": "Registered Number",
          "addToDefaultView": true,
          "isRequired": true
          "verb": "addSPField",
          "fieldType": "Note",
          "displayName": "Extra Notes",
          "isRequired": false
  "version": 1

Adding a Site Script in tenant

  • Open SharePoint Online Management Shell and run below code with proper data.
$adminSiteUrl = "" #Add your tenant admin URL.
$siteScriptFile = "c:\scripts\site-script.json" #File path of JSON file.
$siteScriptTitle = "Contoso Site Script"    #Give title to your Site Script.
$cred = Get-Credential
Connect-SPOService $adminSiteUrl -Credential $cred
Get-Content $siteScriptFile -Raw | Add-SPOSiteScript -Title $siteScriptTitle
  • Once Site Script will be added to tenant. It will show details for that Site Script. Note down Site Script ID to use it later.
$adminSiteUrl = "" #Add your tenant admin URL.
$siteScriptFile = "c:\scripts\site-script.json" #File path of JSON file.
$siteScriptTitle = "Contoso Site Script"    #Give title to your Site Script.
$cred = Get-Credential
Connect-SPOService $adminSiteUrl -Credential $cred
Get-Content $siteScriptFile -Raw | Add-SPOSiteScript -Title $siteScriptTitle

Creating a new Site Design and attach Site Script 

  • Create new Site Design in tenant using below PowerShell script.
$webTemplate = "64" #64 = Team Site, 68 = Communication Site, 1 = Groupless Team Site
# You can pass multiple Site Script IDs as an array.
Add-SPOSiteDesign -Title "Contoso Site Design" -WebTemplate $webTemplate -SiteScripts "127cb6a9-dc14-44d4-8962-d3821d61e802" -Description "Creates list and applies theme."

SiteScripts attribute contains the Site Script ID which is copied from the earlier step.

  • You can see below output after Site Design successfully added.

Sharepoint Online Management Shell

  • Open SharePoint landing page in your tenant. You will see new Site Design option for team site while creating a new site as below.Team Site

Creating a new team site using Site Design

  • Open SharePoint landing page in your tenant and click on “Create site”.
  • Select Team Site option and create a new site.
  • Once click on “Finish” button, you will see your new site in default theme. You can also notice one warning message below Suite bar showing “Applying Site Design. We are updating your site based on the design you chose.”Create Site
  • Click on “View progress” will show you the progress for applying Site Design.View Progress
  • Click on “View updated site” will refresh your site with configurations applied via site design. “Custom Cyan” theme is applied to site.Apply Site Design

“Students Information” list is created in site.

Create a list

Updating existing Site Script and Site Design

Site Script

You can edit your existing Site Script by using Set-SPOSiteScript commandlet. You can assign new JSON file to existing Site Script as below.

$siteScriptId = "127cb6a9-dc14-44d4-8962-d3821d61e802"
$siteScriptFile = "c:\scripts\New-site-script.json"
Set-SPOSiteScript -Identity $siteScriptId -Content (Get-Content $siteScriptFile -Raw)

Site Design

You can edit your existing Site Design by using Set-SPOSiteDesign commandlet. You can add new site script or remove site script from site design using the commandlet. You must pass all required Site Script file IDs in commandlet to update Site Design.

$siteDesignId = "ff0b989d-2282-4527-a705-95e17150c6a0"
Set-SPOSiteDesign -Identity $siteDesignId -SiteScripts "127cb6a9-dc14-44d4-8962-d3821d61e802", "6142d2a0-63a5-4ba0-aede-d9fefca2c767"

Deleting existing Site Design and Site Script

You can delete Site Design and Site Script from tenant at any time using Remove-SPOSiteDesign and Remove-SPOSiteScript commandlets along with ID as identity. Deleting the Site Design will not delete Site Script directly, you will require to delete both separately using commandlets.

Remove-SPOSiteDesign -Identity "ff0b989d-2282-4527-a705-95e17150c6a0"
Remove-SPOSiteScript -Identity "127cb6a9-dc14-44d4-8962-d3821d61e802"

Applying Site Design using code

  • You can apply Site Design using CSOM, REST and PowerShell. However, applying default Site Design to existing site is not possible.

Here, below is the PowerShell script to apply Site Design to your site.

$adminSiteUrl = ""
$siteUrl = ""
$siteDesignId = "ff0b989d-2282-4527-a705-95e17150c6a0"
$cred = Get-Credential
Connect-SPOService $adminSiteUrl -Credential $cred
Invoke-SPOSiteDesign -Identity $siteDesignId -WebUrl $siteUrl
  • If your Site Design has more than 30 verbs in total, you will have to use Add-SPOSiteDesignTask commandlet.

Limiting who can use Site Design

  • There are the cases, when you want to restrict users from using Site Designs to create new site, that can be possible by granting permissions. By default, all designs are available to all users and groups, but once you assign permissions to Site Design, user can see Site Designs on which they have permissions.
  • You can assign several permissions to users or groups by passing several principals with comma separated.
  • Permissions can be granted to users or groups using Grant-SPOSiteDesignRights commandlet.
$siteDesignId = "ff0b989d-2282-4527-a705-95e17150c6a0"
Grant-SPOSiteDesignRights -Identity $siteDesignId -Principals $principals -Rights View
  • Permissions can also be removed using Revoke-SPOSiteDesignRights commandlet.
$siteDesignId = "ff0b989d-2282-4527-a705-95e17150c6a0"
Revoke-SPOSiteDesignRights -Identity $siteDesignId -Principals "[email protected]"

Adding Site Design for Hub Site Site

Designs can also be possible to attach to Hub sites. This means when you attach your site with Hub Site, Site Design will be executed on your site. Web template ID is passed and so adding a Site Design in tenant is not necessary to match with the site when you are planning to join it to Hub site. You can join both Team Site and Communication Site designs to Hub.

  • There are 2 ways to associate Site Design to your Hub site using either user interface or code.
  • To associate Site Design using user interface, you need to go your Hub Site > click on gear icon on upper right corner > Hub site settings > select design you require.Select design
  • You can associate Site Design using PowerShell script to your Hub site. Currently, there is no support provided for REST API.
$hubSiteUrl = ""
$siteDesignId = "ff0b989d-2282-4527-a705-95e17150c6a0"
Set-SPOHubSite $hubSiteUrl -SiteDesignId $siteDesignId

Provision a site using Site Design, Site Script and PnP Provisioning engine

Though Site Design and Site Scripts are very useful in applying configurations during new site creation, if there is a need to setup configuration at large level, PnP Provisioning engine is quite life saver. PnP Provisioning engine provides various features at vast level than Site Design and Site Scripts. One of the best actions in Site Script is to trigger a MS Flow. Using this, you can trigger PnP provisioning engine scripts on your newly created site. Let us see some steps at high level as below:

  • Create a Site Design and Site Script which can trigger MS Flow with required parameter.
  • MS Flow will add specific value in Azure Storage Queue.
  • Azure Storage Queue triggers an Azure function to run PnP provisioning engine scripts. You can find detailed steps for calling PnP provisioning engine from a Site Script from here.


You have seen that Site Designs and Site Scripts are very useful, easy and require less efforts when there is a need of same configurations for all sites in tenant. Every organization has certain constraints/configuration that needs to be added in each newly created site in tenant. Large organizations work on different projects at a time and requires different sites in their tenant. Creation of sites and configuration setups often increases overhead for tenant admins and it results in lower productivity. With the use of Site Design & Site Scripts, tenant admins or any authorized users can create new sites by selecting designs as per their need, increases the productivity and lowers the burden for admins.


  • Leave a message...

Related Articles

Power Apps – Portals (Part 3)

Sep 15, 2020

HIPAA Compliance Healthcare Software Development

Sep 9, 2020

Power Apps – Model Driven Apps (Part 2)

Sep 7, 2020