Working with the Side Panel

Incorporating a Side Panel into your Help Scout app offers a dedicated space to display supplementary content, whether it be intricate details, comprehensive data views, or interactive forms. As your application evolves, the side panel becomes a powerful tool in extending the breadth of features and interactions you can provide within Help Scout.

One of the main utilities of the Side Panel is its ability to display content from an external URL. This makes it versatile for various applications, ranging from showing in-depth details of e-commerce orders to providing interactive forms for tasks like creating a Jira issue.

Opening the Side Panel from Your Application

The SDK offers an easy way to launch the Side Panel with the content of your choosing. To open it, simply provide the URL that should be loaded within the Side Panel iframe.

Here’s how to utilize the new method:

import HelpScout from '@helpscout/javascript-sdk';

// Open the side panel and load content from the provided URL

When executed, this will prompt Help Scout to open a Side Panel to the right of the main content area. The content from the specified URL will then be loaded within an iframe inside the panel. This allows you to have a rich, integrated experience right within Help Scout without navigating the user away from their current view.

Best Practices for Side Panel Content

When designing content for the Side Panel:

  1. Responsive Design: Ensure your content is optimized for the Side Panel’s width and height. Given its dimensions (400px wide by 100% height), the design should be responsive and legible.

  2. User Experience: Consider providing a clear way to navigate or interact with the Side Panel content. While an intuitive back action or other navigation aids can enhance the user’s journey, remember that Help Scout automatically includes a close button for the Side Panel. Ensuring that your design is user-friendly is crucial for an optimal experience.

  3. Interactive Elements: If your Side Panel contains interactive elements like forms, ensure that there’s feedback upon submission. For instance, if a user creates a Jira ticket, confirm the action using a success notification. Consider leveraging the showNotification() method from our SDK to provide consistent and seamless feedback to the users.

  4. App Loading Experience: While Help Scout provides a loading indicator for the initial iframe load, it’s crucial for apps to maintain this experience beyond the initial load. If your app has asynchronous operations that fetch additional content or data, consider implementing your own loading indicators or placeholders. This ensures that users are always informed and are not left wondering if something is happening in the background. Keep in mind that our React UI Kit includes a Spinner component you could use for this!

  5. Consistent Styling: To maintain a consistent look and feel with the rest of the Help Scout interface, consider using styles from the Help Scout Fonts and Styles Guide or the React UI Kit.

Integrating the Side Panel into your application enriches the user experience, offering more detailed views and interactions without overwhelming the main interface. As with all features, it’s essential to keep user experience at the forefront of your design decisions.

Working with the Side Panel: Practical Example

Imagine you’re developing an e-commerce app integrated with Help Scout. Your main interface lists order numbers, and you want your users to access more detailed information about an order when they click on an order number.

Here’s how you could achieve this:

HTML Structure:

<div class="orders-list">
  <!-- Sample order listing -->
  <a href="#" class="order-link" data-order-url="">Order #12345</a>
  <!-- ... other orders ... -->

Each order link contains a data-order-url attribute, which holds the URL to the specific order details. This URL will be loaded into the Side Panel.


import HelpScout from '@helpscout/javascript-sdk';

document.addEventListener('DOMContentLoaded', () => {
  // Get all order links
  const orderLinks = document.querySelectorAll('.order-link');

  // Attach event listeners
  orderLinks.forEach(link => {
    link.addEventListener('click', (event) => {
      // Get the URL for the order details from the clicked link
      const orderUrl = event.currentTarget.getAttribute('data-order-url');

      // Open the Side Panel with the order details

When an order link is clicked, it retrieves the specific URL for that order from the data-order-url attribute and opens the Side Panel using the openSidePanel method from the SDK.

Side Panel Content (orderUrl):

When the orderUrl is accessed, it could render an HTML page with a structure like the following:

<!DOCTYPE html>
<html lang="en">
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Order Details</title>

<div class="order-details">
  <h2>Order #12345 Details</h2>
  <section class="customer-details">
    <h3>Customer Information</h3>
    <p><strong>Name:</strong> Jane Doe</p>

  <section class="items">
    <h3>Ordered Items</h3>
      <li>Product Name - Quantity: 2 - Price: $20.00</li>
      <li>Another Product Name - Quantity: 1 - Price: $50.00</li>
      <!-- ... other items ... -->

  <section class="shipping-status">
    <h3>Shipping Status</h3>
    <p>Shipped and expected to be delivered by May 10, 2023.</p>


This simple structure provides a clear idea of what order details could be presented in the Side Panel once a user clicks on the respective order link or button.