Add Hero Web Part using SharePoint PnP PowerShell

Hero web part is one of the out-of-the-box modern web parts, visible on all new communication sites but also usable in team sites. It allows the author of the page to add images, text and links to different web pages, usually on the same site. In essence, it's a big and colorful link list. In this article I'll explain how you can add and configure Hero web part to modern SharePoint pages using SharePoint PnP PowerShell.

A hero web part in action! A hero web part in action!

To add a Hero web part to a page, use Add-PnPClientSideWebPart commandlet. It takes just a few arguments as you can see in the example below.

Add-PnPClientSideWebPart -Page $page -DefaultWebPartType Hero -Section 1 -Column 1 -Order 2 -WebPartProperties $heroProperties

The Page parameter referst to the modern page. Before adding the web part use Add-PnPClientSidePage to create a new one or Get-PnPClientSidePage to get a reference to an existing one. DefaultWebPartType is Hero when we are adding a Hero web part. Section, Column, and Order parameters refer to the place where you want insert the web part into. All of these are integers which start from number 1. You can access sections using $page.Sections collection and add new sections using Add-PnPClientSidePageSection commandlet. When you add a section, you specify SectionTemplate, which defines how many columns are in the section.


Finally the Order parameter of Add-PnPClientSideWebPart refers to the index of web parts inside a column, while Order in AddPnPClientSidePageSection refers to the index of sections in a page.

Hero web part properties

Only complex parameter in Add-PnPClientSideWebPart is WebPartProperties. Depending on the type of the web part you are adding, you need to specify different set of properties in json format. The complex part of this parameter is that the documentation is a bit lacking, so you usually find out the correct set of properties via trial and error - or you just google to find a page like this.

When adding web part properties to Hero web part, we have a json format that consist of high level properties and a collection of 1 to 5 content elements.

High level properties of Hero web part

You can control the web part layout (tiles vs. layers) by setting layoutCategory property to either 1 or 2. The property layout controls how many items are shown from the content collection which is an array of items.

Content element properties of Hero web part

The real magic of Hero web part happens in content collection as detailed in the image above. You can specify image used in the content element using the url property of image object. Hero web part element has main text element which is controlled by title and showTitle properties and secondary text element which is controlled using callToActionText and showCallToAction properties. Set isCustomImageLoaded to true and isDefaultImage and isDefaultImageLoaded to false in order to use the image you have specified above. Use link property to specify the web page that is opened when this element is clicked.

Finally, here is a sample script you can try out. Remember to upload the images to site asset library. If you want to do this with PowerShell, use Add-PnPFile commandlet. Also note, that you can use Set-PnPClientSideWebPart instead of Add-PnPClientSideWebPart if you don't want to add a new web part but instead modify an existing one.

Connect-PnPOnline -url $page = Get-PnPClientSidePage "Home" $heroProperties = @" { "heroLayoutThreshold": 640, "carouselLayoutMaxWidth": 639, "layoutCategory": 1, "layout": 2, "content": [{ "type": "Web Page", "color": 4, "image": { "url":"/sites/products/SiteAssets/foodpic1.jpg" }, "title": "Appetiser can be the best course", "showTitle": true, "imageDisplayOption": 3, "callToActionText": "Select your appetiser now!", "showCallToAction": true, "isDefaultImage": false, "isDefaultImageLoaded": false, "isCustomImageLoaded": true, "showFeatureText": false, "link":"/sites/Products/SitePages/Appetisers.aspx", "previewImage": { } }, { "type": "Web Page", "color": 4, "image": { "url":"/sites/products/SiteAssets/foodpic2.jpg" }, "title": "Main cources", "showTitle": true, "imageDisplayOption": 3, "callToActionText": "You can start with a main course", "showCallToAction": true, "isDefaultImage": false, "isDefaultImageLoaded": false, "isCustomImageLoaded": true, "showFeatureText": false, "link":"/sites/Products/SitePages/Main-courses.aspx", "previewImage": { } }] } "@ Add-PnPClientSideWebPart -Page $page -DefaultWebPartType Hero -WebPartProperties $heroProperties -Section 1 -Column 1 -Order 1