Use Visualforce in Lightning Experience

Lightning bolt icon used to indicate that the content is for Lightning Experience

Attention, Trailblazer!

Salesforce has two different desktop user interfaces: Lightning Experience and Salesforce Classic. This module is designed for Lightning Experience.

You can learn about switching between interfaces, enabling Lightning Experience, and more in the Lightning Experience Basics module here on Trailhead.

Learning Objectives

After completing this unit, you’ll be able to:
  • List at least five Visualforce features that work unchanged in Lightning Experience.
  • Describe at least two Visualforce features you need to review in your Visualforce code.
  • List at least two Visualforce features that don’t work in Lightning Experience.
  • Describe how the Lightning Experience affects the visual design of existing Visualforce pages.

Visualforce and Lightning Experience

Lightning Experience is a whole new world, and we hope you think it’s exciting. Behind the Lightning Experience user interface is a new way of delivering the Salesforce application, one that brings significant changes to the way Visualforce apps run. For the most part, your Visualforce apps should “just work,” but there are some things you should know before you make the jump to Lightning Experience.

The technical details of how Lightning Experience is built and how it runs Visualforce apps are really cool, and important for actual development work. When you’re ready for those details, the Visualforce & Lightning Experience module will show you the way. But here we’re going to stay at a high level, and divide things up into what works and what doesn’t, what you’ll want to update, and other issues that will help you plan your Lightning Experience migration development effort.

What Works

The list of what parts of Visualforce work in Lightning Experience is pretty long. It’s very nearly as long as the entire Visualforce features list. So before we get to the things that aren’t on the list, let’s think positive, and check off some of the many things you can count on.
First of all, the fundamental mechanisms of how Visualforce works remain the same. Whether your pages use the standard controller, custom controllers, JavaScript remoting, or Remote Objects, your connection to Salesforce works the same.


If you’re using JavaScript extensively, or if you’re using other APIs to access Salesforce, you might have some work to do. We’ll get to that.

Second, Visualforce markup remains the same. There are a few tags and attributes that behave differently in Lightning Experience, and a very few that we recommend against using or that just don’t work. But otherwise the way you write code for Visualforce pages and components is unchanged.

Third, most of the ways you can use Visualforce to customize your organization work just fine in Lightning Experience—though as you can no doubt imagine, with an all new user interface, these customizations have moved to different places.

Let’s dive just a bit into the specifics of these customizations. All of the following work just fine in Lightning Experience, simply moving to a new location in the user interface.
  • Creating custom tabs and apps with Visualforce pages.
  • Creating custom buttons and links that lead to Visualforce pages.
  • Creating custom actions that open with a Visualforce page.
  • Overriding standard actions with Visualforce pages (with one exception that we’ll get to later).
  • Creating flows that use Visualforce pages.
  • Packaging Visualforce pages and components.
The changes in the user interface vary from minor to significant. Features customized with Visualforce move automatically when users change between Lightning Experience and Salesforce Classic. You might need to give your users an initial orientation, but after that, they’ll be happy as clams.

There are other features, such as Visualforce email templates, that use Visualforce code behind the scenes. These aren’t surfaced in the user interface directly, and so they remain unchanged.

For a screenshot-heavy visual tour of where various features have moved to, see the Use Visualforce in Lightning Experience unit in the Visualforce & Lightning Experience module.

What Works, but Needs Updating and Testing

The environment in which a Visualforce page runs when Lightning Experience is enabled is different than the standard Visualforce request. The technical details get pretty complex, but the simple version is that in Lightning Experience, Visualforce pages are embedded in an HTML iframe that’s displayed inside the Lightning Experience app.

This change has a number of consequences that mostly have to do with JavaScript and accessing external apps. You’ll want to review your code and verify a few things before you certify your Visualforce pages for use in Lightning Experience. We’re saving the nitty gritty details for the Visualforce & Lightning Experience module. For now, let’s just check in at a high level so you can start to scope your review.

For starters, if you have pages or apps that use JavaScript, you’ll want to review the behavior of the code. In particular, your code can’t directly access the window global object. You can still get at it with a minor code change if you really need to, but there are probably better ways to accomplish those tasks using Lightning Experience app APIs instead. In particular, code which sets window.location directly should definitely be revised to integrate with the Lightning Experience navigation stack.

Similarly, code that assumes that it has access to the entire environment is in for a rude surprise. It still has access to the Visualforce part of the document, but not the full Lightning Experience app. That will be fine for many apps, but for those that want to be totally in charge, there’s going to be some work for you to do.

If your pages make use of iframes themselves, either with <apex:iframe> or static HTML, being embedded into another iframe could cause some issues. In many cases “turtles all the way down” is fine. Just make sure you do extra testing here.

If your pages embed a Canvas app, and especially if you’ve used the Canvas APIs to integrate the app into Salesforce, allocate time for thorough testing as well. Canvas apps use an iframe, and while correctly behaving code should just work, we all know how common perfect code is in the real world.

Pages that use Remote Objects and JavaScript remoting work without requiring updates to authentication code. However, if your pages use other Salesforce APIs you might need to adapt your authentication code to make the right cross-domain request, or otherwise adjust to the new environment.

All of the above sounds both vague and hard to do but, in truth, the amount of code you’re likely to need to change is small. And again, the details for developers are available in the Visualforce & Lightning Experience module.

What Doesn’t Work

And so we come to the, shall we say, less pleasant part of our conversation. Fortunately, the list of what doesn’t work in Visualforce for Lightning Experience is short, and we can get through it quickly.

Perhaps the most significant change, in terms of things that might be hard to work around, Visualforce overrides of standard actions are slightly different in Lightning Experience compared to Salesforce Classic. Any override for the object list action won’t be accessible in Lightning Experience.

Specifically, there are six standard actions you can override for most standard and all custom objects in Salesforce Classic:
  • Object tab
  • Object list
  • Record view
  • Record edit
  • Record create
  • Record delete
In Lightning Experience the first two actions have been combined into one page, object home. Object home is similar to object list, along with some elements of object tab, like recent items. Other elements, such as reports or tools, have moved to other parts of the user interface.

Regardless of the user interface settings in your organization, both object tab and object list are available to be overridden in Setup. Overriding the object tab action overrides the object home page in Lightning Experience, as expected.

However, when in Lightning Experience, the object list action isn’t accessible in the user interface, so there’s no way to fire it. If your organization has overridden the object list action for any object, that functionality won’t be available when users are using Lightning Experience. If there are essential features in that override, you’ll need to find another way to make them available.

On a bit smaller scale, the showHeader and sidebar attributes of <apex:page> have no effect on Visualforce pages when displayed in Lightning Experience. The standard Salesforce Classic header and sidebar are always suppressed, and there isn’t a way to suppress the Lightning Experience header and sidebar.

A number of related lists available in Salesforce Classic aren’t supported in Lightning Experience. The <apex:relatedList> component isn’t a way around this limitation. Good try, though!

And, coming down to the really minor issues, rendering Visualforce pages as PDFs works exactly as in Salesforce Classic, without any of the Lightning Experience visual design. This is probably what you want anyway, but if you wanted to render pages into PDFs that include the Lightning Experience design, that’s not possible today.

That Look-and-Feel Thing

The first thing you notice about Lightning Experience is the gorgeous, all new visual design. And if you’ve been developing Visualforce pages for a while, your next thought might be, how will my Visualforce pages look in Lightning Experience. The short answer is…well, let’s sit down for this part, OK?

The short answer is, with the exception of suppressing the Salesforce Classic header and sidebar, and of being framed by the Lightning Experience user interface, Visualforce pages display unchanged in Lightning Experience.

Specifically, the HTML that’s rendered by the built-in Visualforce components doesn’t change when the page displays in Lightning Experience, and the Salesforce Classic stylesheets those components use is, by default, loaded by the page. The effect is that pages that use <apex:inputField>, <apex:outputField>, the <apex:pageBlock> components, and other coarse- and fine-grained components that match the Salesforce Classic visual design, still match that visual design. You get a little slice of Salesforce Classic in the middle of your Lightning Experience.

If, however, you’ve used Visualforce components that are relatively unstyled, or your own components and markup, and developed your own stylesheets instead of using the default Salesforce styles, your pages also appear unchanged, retaining the styling you worked so hard to develop.

In other words, in Visualforce for Lightning Experience we’ve favored stability in the visual design of existing pages, instead of trying to adapt them dynamically to Lightning Experience.

That said, if you’re as excited about the new visual design as we are, there are ways for you to adopt that styling to a lesser or greater degree, depending on how much work you want to put in. We won’t cover it here, but there’s a whole unit, Understanding Important Visual Design Considerations, that shows the range of possibilities and the techniques to use to achieve them.