Customizing the "modern" experiences in SharePoint Online

SharePoint Online has started the gradual introduction of "modern" experiences across the SharePoint service, which has a direct impact not only on the end user experience but also on the customization options that can be used. This article provides an overview of the "modern" experiences to get you started, including links to articles containing all the customization options for each of the "modern" experiences.

Numerous benefits in the "modern" experiences are called out in the referenced materials, but if you have specific customization requirements, you should be aware of the currently supported options for customizations.


We're not deprecating the "classic" experience; both "classic" and "modern" will coexist.

What are the "modern" experiences in SharePoint Online?

The "modern" experiences in SharePoint Online are:

  • Modern team sites
  • Modern list and library experiences
  • Modern site pages

"Modern" experiences are being gradually released in SharePoint Online, and you can control how they are applied at the tenant or site level. If you have existing customizations, you can defer using the new experiences until the required customization options are available.

If you have existing customizations that are business critical for your deployment, we recommend using the following process for adopting the "modern" experiences:

  1. Readiness: Understand the "modern" experiences, know what features they offer, but equally important, understand which features are not (yet) available.

  2. Assess: Assess to what extent your current customizations can work within the "modern" experience. Also assess which of your sites have customizations or features that will not work within the "modern" experiences. These sites and their customizations should be updated or need to stay in "classic". However, other sites should work just fine using the "modern" experiences. The best way to assess your compatibility with the "modern" experiences is by using the SharePoint Modernization scanner.

  3. Solution planning: Plan the work required for both custom solutions and sites to prepare them to be used with the "modern" experiences.

  4. Develop and test: Apply the needed changes to your customizations and test them.

  5. Deploy: Roll out the updated changes to your SharePoint Online environment.

Following are the key scenarios currently supported by the "modern" experiences. We will be updating the list of supported scenarios whenever new capabilities are introduced in SharePoint Online.

Customization/Article Description
Provisioning "modern" team sites programmatically "Modern" team sites can be provisioned by an end user, but you can also create these sites programmatically.
Customizing "modern" team sites "Modern" team sites are sites that bring a fresh, new responsive user experience to SharePoint Online,
showing relevant information on the home page. Typically, these sites also have an associated Microsoft 365 group.
Customizing "modern" lists and libraries "Modern" lists and document libraries bring a better user experience that is faster, more intuitive, and responsive.
This article focuses on the extensibility options, such as user custom actions and branding, which are supported for the "modern" library and list experiences.
Customizing "modern" site pages "Modern" team site pages are fast, easy to author, and support rich multimedia content. Additionally, these pages
look great on any device, in a browser, or from within the SharePoint mobile app.
This article focuses on the extensibility options available within the "modern" page experience.
SharePoint "modern" sites classification Configure out-of-the-box site classification for modern SharePoint sites.

Converting existing sites to "modern" team sites

Existing collaboration sites cannot be converted to "modern" team sites with an associated Microsoft 365 group, but you can however associate a new Microsoft 365 group to existing collaboration site. You can also start using modern page and list experiences in the classic sites, which will make them look like a modern group associated team sites.

"Modern" lists and library usage can be controlled at site, web, and list/library level. You can find more details about the available options in our "modern" list and libraries article.

By default, "classic" SharePoint sites use modern pages for any newly added page, and you have the option to change the welcome page to a modern page. Setting a new "modern" page for a "classic" SharePoint site can be done programatically by using CSOM or REST APIs.

Using modern experiences in the root site collection of a tenant

Root site collection of Office 365 tenant is always using classic team site template and it's not supported to recreate this site collection using user interface, PowerShell or APIs. You can however start utilizing modern experiences on this root site by creating content using modern pages.

It is also supported and possible programmatically enable home page layout in the root site collection. This will provide flexibility for the welcome page designs for this site.


It is not supported to delete or replace existing site collection from the root URL of your tenant. You should not in any circumstances delete the root site collection. Technically this can be performed using APIs, but that can cause the tenant to move into inconsistent status.

Enable home layout in collaboration site

You can use CSOM, REST APIs or PnP PowerShell to enable home layout in the pages library. Following example uses PnP PowerShell from simplicity perspective, but other options are also supported.

# Connect to the site

# List all pages, and find the id of the modern page which you want to change
Get-PnPListItem -List SitePages

# Change layout from "Article" to "Home" to remove top banner
Set-PnPListItem -List SitePages –Identity <id> -Values @{"PageLayoutType"="Home"}


PnP PowerShell is an open-source solution with active community providing support for it. There is no SLA for the open-source tool support from Microsoft.

SharePoint "modern" experiences support for on-premises

The SharePoint "modern" experiences are supported in SharePoint 2019 in on-premises. Also as part of the SharePoint 2016 Feature Pack, "modern" experiences will be introduced within the OneDrive for Business experience, and you can take advantage of the SharePoint Framework client-side web parts in the classic page experience.

See also