We’re always trying to experiment with what’s possible with branding SharePoint. As one of the developers on the PixelMill team, I knew it was long overdue to try my hand at playing with the relatively new custom header and footer available in modern pages through custom SharePoint Framework (SPFx) Extensions. I decided to see if I could mimic a branded header bar by adding a logo into the header that would link back to the home page.

Prereqs

If you’re brand new to SPFx as I was, you’ll definitely want to head over to the good folks at Microsoft, who have lots of guided tutorials and videos to get you started. At the very least, you should:

• Set up your O365 tenant and development environment
• Work through the Build your first SharePoint Framework Extension tutorial
• Work through the Use page placeholders from Application Customizer tutorial — This is our starting point!

Let’s do this!

At this point, your extension makes use of the Top and Bottom placeholders in modern pages to inject HTML. The header and footer content are defined by the properties passed to the query string parameters:
/sites/TeamSite?loadSPFX=true&debugManifestsFile=
https://localhost:4321/temp/manifests.js&
customActions={%22459e9d09-3ced-4486-8f80-6c2c92cc49b6%22:{%22location%22:%22ClientSideExtension.ApplicationCustomizer%22,%22properties%22:{%22Top%22:%22Top%20area%20of%20the%20page%22, %22Bottom%22:%22Bottom%20area%20in%20the%20page%22}}}

Those properties would be a pretty handy way to pass in an image URL so that you wouldn’t have to hard-code the image URL into the injected code. So that’s exactly what we’ll do!
In the rest of this tutorial, we will:

• Add the image to the site assets,
• Modify the code to pass in the image URL, and
• Modify the rendered HTML code and CSS to display the image and link to the home page

First, upload the image you’d like to use into the Documents > Site Assets folder of your site (or really, any other location where you’d like to keep your image). Make a note of the image location URL.

Fire up your code editor to modify your previously-created HelloWorld extension.
Open src/extensions/helloWorld/HelloWorldApplicationCustomizer.ts. Look for the section where you define the IHelloWorldApplicationCustomizerProperties.

Add a new line for the Logo:

Now look for the section where the top placeholder is set:

In the code below, I’ve added a logoString variable to hold the Logo property, then modified the HTML to add a link to the site home page, the image itself, and the original top text standing in for the image ALT attribute.

Now open AppCustomizer.module.scss. Modify this with additional styles to format the image and top bar. I added some padding, removed the height of the top bar, and kept the logo to be 80px or less.

Finally, open /sharepoint/assets/elements.xml and modify the ClientSideComponentProperties to add in the Logo property:

How it looks

If you don’t already have gulp running, go ahead and run gulp serve –nobrowser.
Then, open up a modern page and append this to the URL (don’t forget to replace the application ID with your own from the HelloWorldApplicationCustomizer.manifest.json and to link in your own logo image location):

Click “Load debug scripts” to allow the script to run locally.

And you’ll see your image, linking to the home page, in the top header!

Now what?

You might be wondering how this would all deploy to SharePoint. I would suggest that you continue with the tutorials at Microsoft, starting from Deploy your Extension to SharePoint. One thing you’ll notice, though, is that there is no current interface for setting those Extension properties — you just install the solution as-is. What if you want to change the image location for some sites?
That’s where this handy PnP-Powershell command comes in: Add-PnPCustomAction. You can try doing something like this while connected to your SharePoint site in Powershell:

Use with caution!

Unfortunately, it looks like my pretty image logo and visions of a fully branded and functional header are going to need to go back to the drawing board. While I’ve demonstrated that it’s possible to add some branding to the top of a Modern site, doing so effectively reduces the usable, scrollable section of the page. This becomes especially evident on a document library page:

While having the Top and Bottom placeholders are exciting, it will definitely take some good UX + UI work to make best use of the limited space. Our designers are already dreaming of some different things to try for upcoming Modern projects! If you’ve been coming up with some creative uses for the Top and Bottom placeholders, we’d love to hear about it in the comments below!

Corrie Haffly
Senior Web Developer
Sea Otter Enthusiast
Your SharePoint Tour Guide