How to Implement a Loading Dialog Box in Salesforce — The Easy Way

You have created the perfect page. The layout is just right, you have embraced ajax and are doing partial page updates all over the place. But how do you deal with server latency or ajax requests that have to chug through a mountain of data? If only there were a simple component that you could add to your page that would handle all of the messy JavaScript and CSS associated with those slick loading dialog boxes. Well, you’re in luck!



The Problem

Since the whole “Web 2.0” craze of 2005, ajax requests and partial page updates have gone from a “slick upgrade” to “standard functionality”. Fortunately, Salesforce gives us a lot of great tools for creating ajax requests. But unless you are a front-end guru, dealing with the minutia of cross-browser CSS and JavaScript code to make a loading dialog box may seem a bit daunting.

The Solution

Fortunately, I have a super simple solution. By adding the Visualforce Component below, you will be able to implement a fancy loading dialog box with a single line of code!

YouTube blocked at work? No Headphones in the office? No worries, Just keep reading!


To add the code to your Salesforce org:

  1. Open up the Developer Console (or your IDE of choice)
  2. Got to File New Visualforce Component
  3. Give the component a name. For this tutorial, I called the component loadingDialog
  4. Copy the Visualforce Component code below and paste it into the new component
  5. Click File Save (or type Ctrl+S)

Visualforce Component Code

The most important part of this tutorial is the Visualforce Component. It is not critical that you understand every line of the code in the Component as long as you understand how to implement it. However, there are a few things you should take note of.

The Attributes

There are 3 attributes that you can set when you initialize the component in your Visualforce page. All three are optional and have default values.

Name Data Type Required Default Value Description
title string false “Please Wait” The title of the dialog box. This is text that will show up as bold text at the top of the box.
message string false “Working…” The message of the dialog box. This is text that will appear inside the dialog box next to the spinning animated image.
width integer false 350 The width of the dialog box in pixels. If you need to set the width of the box in another increment, such as percentage, you can overwrite the CSS.


There are also a number of IDs defined in the DOM that can be targeted with CSS to overwrite the look of the dialog box.

Selector Description
#modalBlocker This is the id of the <div> tag that covers the screen and prevents the user from clicking anywhere else on the screen. By default, it is a dark semi-transparent element that covers the entire screen.
#modalBox This is the outer container of the dialog box.
#modalBox-inner This is the inner container of the dialog box.
#modalBox-inner h3 This is the heading tag that contains the dialog box title
#modalContent This is a wrapper for the content (below the title)
#modalBox .spinner This is the animated spinning image

The JavaScript Functions

These functions can be called by page elements such as an <apex:commandButton> tag to hide and show the box as well as modify its contents

Name Arguments Description
showLoadingDialog() none This function will show the loading dialog box. Returns void.
hideLoadingDialog() none This function will hide the loading dialog box. Returns void.
setLoadingDialogTitle(s) string This function will set the title of the dialog box. It takes a single string argument. The string passed into the function can contain plain text or HTML and will result in the title displaying the value passed into the function. Returns void.
setLoadingDialogMessage(s) string This function will set the message of the dialog box. It takes a single string argument. The string passed into the function can contain plain text or HTML and will result in the message displaying the value passed into the function. Returns void.

 Look Maw, No jQuery!

When developing this component, it was important to me that it be very portable. So it doesn’t rely on any frameworks or libraries like jQuery or Bootstrap. This makes it really easy to move from org to org. As a matter of fact, I have added this component to nearly every org I’ve ever worked on and it has proven to be very useful.

How to Implement the Component

As I stated earlier, we can implement this component on any Visualforce page using a single line. Simply add the line of code below to your page. It is recommended that you place this line towards the top of the page. I like to add components like this right after the <apex:page> tag. This insures that if you intentionally want to overwrite anything contained in the component, you will be able to do so after the elements are rendered on the page.


if you want to set the attributes yourself and not use the defaults.

Now you can call the JavaScript functions from anywhere in the page.

 Browser Support

This component has been tested with and works great with all the major browsers going back to IE 7. If you see any issues with future versions of browsers, please let me know in the comments section.

Looks Great in:


Working Example

In this example, we have a page that displays a picklist of Account. When one of the buttons is clicked an ajax request is sent to the controller which gets the Contacts for the selected Account. During this round trip to the server and the partial page update, the loading dialog box will be displayed letting our users know that Salesforce is working hard to get the data they requested.

Visualforce Page

Apex Controller

 If you learned something here, or this helped you in a project, please leave a comment. I’d love to hear about it. Also please consider clicking the “+1” button below or sharing this post on your favorite social network. Happy Partial Page Updating 🙂

Leave a Reply