I’ve wanted to write this article for a long time. DOM manipulation in SharePoint Framework (SPFx) is one of those topics where the official guidance is clear, but the real-world practice is more nuanced. Microsoft does not recommend or support DOM manipulation in SPFx projects. I teach my students and coaching clients the same thing. But this is very much a case of “do as I say, not as I do.”
In this article, I’ll share why I still use DOM manipulation in certain scenarios, the kinds of things I build with it, and the approach I follow to do it responsibly without putting my customers at risk.
A brief history of how we got here
Before SPFx arrived in 2017, Microsoft offered a few extensibility models for SharePoint: sandbox solutions and the add-in model. Most customers didn’t adopt either approach because they simply didn’t provide the flexibility developers needed to customize and extend SharePoint for their organizations.
Instead, developers relied on the Content Editor and Script Editor web parts to inject JavaScript into pages, often using libraries like jQuery to build full-blown client-side applications. Many also modified the HTML and CSS in SharePoint Online (SPO) page markup directly.
This caused constant friction. Microsoft would update SharePoint’s markup, and developers’ solutions would break. Developers got frustrated. Customers got frustrated. And Microsoft got frustrated because they had no visibility into what people were building, yet they needed the freedom to update the platform.
Here’s the telling detail: in 2015, the Content Editor and Script Editor web parts were the most popular web parts across all SharePoint Online tenants. Microsoft saw how developers were actually building solutions and created SPFx in response.
The contract SPFx established
The goal of SPFx was to create a contract between Microsoft and developers. It defined specific extensibility points, web parts and extensions, where developers could work within designated DOM elements on the page. For most of these, you read from and write to a div element that Microsoft adds for your component. You have full control over what goes inside that element, whether you’re using React or writing plain HTML.
Ever wondered what the SharePoint Framework is? Ever asked yourself "what can I build with the SharePoint Framework?" You're in luck because that's what this comprehensive article answers! This article assumes you don't have to have any prior knowledge or experience with the SharePoint Framework. You'll get answers to your questions "What is the SharePoint Framework?" as well as “What can someone build with the SharePoint Framework?” In this article.
https://www.voitanos.io/blog/spfx-5w1h-what-is-the-sharepoint-framework/
The deal was straightforward: stay within the boundaries Microsoft carved out for you, and they won’t break your solutions when they update the page markup.
DOM manipulation, in this context, means adding or modifying HTML and CSS on the page outside of those designated areas. And Microsoft’s message was clear: don’t do it.
Where I stand today
I tell my students, my course participants, my workshop attendees, and my coaching clients the same thing: avoid DOM manipulation. When I see developers suggesting it to each other, I make sure everyone understands that what’s being proposed may not be in their best interest.
But I also want to be transparent about my own practice.
I don’t have a problem with DOM manipulation. I do it in my solutions when necessary. I don’t do it often, but when I do, I follow a very specific approach to make sure I’m not getting myself or my customers into trouble.
What I build with DOM manipulation
Let me walk through some real-world examples of things I’ve built using DOM manipulation in SPFx.
Full-page dialogs for enhanced editing: I’ll add a dialog that overlays the entire page to provide a more advanced web part editing experience. The same approach works for custom administrative screens available to site owners, tenant administrators, or global administrators.
Analytics packages via application customizers: I use application customizers to add analytics tools like Google Analytics, Application Insights, or Microsoft Clarity to SharePoint pages. These provide a far better picture of how people actually use SharePoint from the client side.
Let’s be honest: the out-of-the-box usage reports in SPO leave a lot to be desired.
Event handlers for telemetry: Beyond basic page tracking, you can attach event handlers to the waffle menu, the suite bar, navigation controls, the help icon, notifications, alerts, and even list and library interactions. These handlers don’t change existing behavior. They just log activity to your telemetry package.
Custom buttons in the waffle menu: I’ve added buttons to the waffle menu that are visible only to site owners and tenant administrators. One example: a button that lets administrators attach a field customizer to a column on an existing list. Normally, field customizers require creating a new site column. This approach lets you attach custom rendering to a specific column on a specific list, and even use different customizers across different lists.
Tenant property management: I’ve built a UI for managing tenant-scoped properties, which is a property bag that’s otherwise only accessible through the REST API or command-line tools like the CLI for Microsoft 365 (M365).
Form customizer installation: Another tool I’ve built lets you install SPFx form customizers on existing lists and libraries without writing any custom code.
SPFx Developer Dashboard
Custom footers and navigation: Maybe you want a custom footer attached at the end of the quick launch because there’s no application customizer for that area. That’s a perfectly valid use case.
My approach to responsible DOM manipulation
If you’re going to do DOM manipulation in SPFx, here’s what I’d strongly recommend. This is the approach I follow myself.
Go in with eyes wide open: Understand that you’re operating outside of Microsoft’s supported boundaries. Be incredibly careful that you’re not breaking an existing SharePoint feature or doing something that could block the rollout of a new feature. Your customers won’t be happy if your solution prevents them from using something great that Microsoft just released.
Wrap everything in defensive code: Whatever you implement, make sure that if it breaks, it doesn’t break the SharePoint user experience. You want to fail gracefully or fail silently. Under no circumstances should your customization take down the page.
Use extensive telemetry: I use telemetry to monitor that my customizations are attaching to the UI correctly and functioning as expected. Just as importantly, I track failures. I want to know immediately when something stops working so I can proactively investigate and fix it, not find out from a frustrated customer.
Be transparent with your customer: If your customer wants something that requires DOM manipulation, make sure they understand exactly what they’re asking for. Be clear that you’re doing something custom that Microsoft does not recommend. It’s not that you can’t do it. It’s not that you shouldn’t do it. It’s that everyone involved should understand the tradeoffs.
Keep everything nondestructive: Anything you build should be something you can uninstall or remove, and SPO should behave exactly as it normally would, as if your customization had never existed.
It’s about being careful, not being afraid
I don’t have a problem with DOM manipulation in SPFx. I do it myself. But when I do, I’m deliberate about making sure my solutions have as little chance as possible of breaking the SharePoint experience. And if something does fail, nobody would even notice because it would never affect the core SharePoint functionality.
Microsoft’s guidance exists for good reason. Most developers should follow it. But if you understand the risks, build defensively, and maintain full transparency with your stakeholders, DOM manipulation can be a powerful tool in your SPFx toolkit.
What do you think?
Do you use DOM manipulation in your SPFx projects?
I’d love to hear about your experiences and approaches. Leave a reaction, drop a comment, or ask questions below.
Microsoft MVP, Full-Stack Developer & Chief Course Artisan - Voitanos LLC.
Andrew Connell is a full stack developer who focuses on Microsoft Azure & Microsoft 365. He’s a 22-year recipient of Microsoft’s MVP award and has helped thousands of developers through the various courses he’s authored & taught. Whether it’s an introduction to the entire ecosystem, or a deep dive into a specific software, his resources, tools, and support help web developers become experts in the Microsoft 365 ecosystem, so they can become irreplaceable in their organization.
