Hello everyone and welcome to my blog. We have all seen that moment where a service agent is working on a record, needs to glance at a related record, and ends up navigating away from the form, losing their context, and clicking Back three times to get where they were. In today’s blog, let’s fix exactly that using the Xrm.App.sidePanes client API in model-driven apps.
App side panes let you show a related record, a list, a web resource, or even one of the new generative pages right beside the record the user is already on, without ever leaving the form. Let’s explore how to build one with a real scenario.
The scenario
Imagine your agents work on the Account form all day. Every time they open an account, they also want to see the primary contact of that account to quickly grab a phone number or email, without navigating away from the account they are servicing.
What we want: the moment an account form loads, a side pane should automatically open on the right, showing the primary contact’s record. That is a perfect fit for side panes. Let’s build it.
Creating the side pane
The API follows a simple two-step pattern. First you call Xrm.App.sidePanes.createPane() to create an empty pane, and then you call navigate() on that pane to load something into it. The createPane method returns a promise, so we chain our navigate call inside the then.
Here is the full function. Register this as an OnLoad event handler on the Account form, and make sure you pass the execution context as the first parameter.
function showPrimaryContactPane(executionContext) {
var formContext = executionContext.getFormContext();
var primaryContact = formContext.getAttribute("primarycontactid").getValue();
// Nothing to show if the account has no primary contact
if (primaryContact == null) {
return;
}
var contactId = primaryContact[0].id.replace(/[{}]/g, "");
// Avoid creating a duplicate pane if one already exists.
// OnLoad can fire multiple times, so always guard with getPane().
var existingPane = Xrm.App.sidePanes.getPane("primaryContactPane");
if (existingPane) {
existingPane.navigate({
pageType: "entityrecord",
entityName: "contact",
entityId: contactId
});
return;
}
Xrm.App.sidePanes.createPane({
title: "Primary Contact",
imageSrc: "WebResources/new_contact_icon",
paneId: "primaryContactPane",
canClose: true,
width: 450
}).then(function (pane) {
pane.navigate({
pageType: "entityrecord",
entityName: "contact",
entityId: contactId
});
});
}
Let’s walk through the important bits:
- paneId – a unique id you assign to the pane. This is important because we use it to check whether the pane already exists.
- The getPane() guard – the OnLoad event can fire more than once in a session. Without this check you would keep stacking up duplicate panes. So we first look up the pane by its id, and if it already exists we just re-navigate it to the new contact instead of creating a fresh one.
- pageType: “entityrecord” – this tells the pane to load a single record. We pass the entityName (contact) and the entityId of the primary contact. Notice we strip the curly braces from the GUID before passing it.
- width – the width of the pane in pixels. Side panes have a minimum width of 300px, so keep that in mind.
Screenshot reference below for output

Showing a list instead of a single record
Single records are not the only thing you can show. Say you would rather show all the open cases for the account as a list in the pane. Just change the pageType to entitylist and pass the table name.
Xrm.App.sidePanes.createPane({
title: "Open Cases",
imageSrc: "WebResources/new_case_icon",
paneId: "accountCasesPane",
canClose: true,
width: 500
}).then(function (pane) {
pane.navigate({
pageType: "entitylist",
entityName: "incident"
});
});
Besides entityrecord and entitylist, the navigate method also supports webresource (pass webresourceName) to load an HTML web resource, and the newer generative page type (pass pageId) if you have started working with generative pages. So the same side pane concept works across all of these.
Managing your panes
Once your panes are open, the Xrm.App.sidePanes object also gives you a few handy methods to control them. Here are the ones I find myself using the most.
// Collapse or expand the entire side pane area
Xrm.App.sidePanes.state = 0; // 0 = collapsed
Xrm.App.sidePanes.state = 1; // 1 = expanded
// Get the currently selected pane and widen it
var selected = Xrm.App.sidePanes.getSelectedPane();
selected.width = 400;
// Get a specific pane by its paneId and close it
var casesPane = Xrm.App.sidePanes.getPane("accountCasesPane");
if (casesPane) {
casesPane.close();
}
// Show a notification badge on the selected pane
Xrm.App.sidePanes.getSelectedPane().badge = 1;
The getAllPanes() method is also available if you ever need to loop through every active pane. The badge is a nice way to nudge the agent that something changed in a pane they are not currently looking at.
A few things to keep in mind
- App side panes are not available for on-premises Dynamics 365 Customer Engagement deployments.
- They are supported in web browsers and are not rendered inside the native mobile players.
- Pages inside a pane have a minimum width of 300 pixels, so design accordingly.
- This createPane API is the modern replacement for the older Xrm.Panels.loadPanel approach, which only supported a single pane and did not preserve state well. If you are still using loadPanel, this is your upgrade path.
Final thoughts
Side panes are one of those small features that make a real difference to day to day usability. With just a createPane and a navigate call, you can keep your users in context and save them a lot of unnecessary clicking. Try it out on one of your busy forms and watch how much smoother the experience becomes.
For the complete API reference and the full list of options, refer to Microsoft’s documentation:
- Creating side panes by using a client API in model-driven apps
- Xrm.App.sidePanes (Client API reference)
Hope this helped. You will also like the below posts.
Debajit Dutta
Discover more from Debajit's Power Apps & Dynamics 365 Blog
Subscribe to get the latest posts sent to your email.