I recently had a reason to look more closely at the standard apex:include component in Visualforce, and I'm intrigued by the intent behind this component. Would anyone be willing to share some perspectives on when and why it would be more appropriate to use apex:include vs. a custom Visualforce component?

It seems to me that Visualforce custom components do the same thing as an apex:include element, and Visualforce custom components have the added benefit of being able to accept custom attributes. The only use case I can imagine right now for using apex:include is to bring in a page from a managed package.

3 Answers 3


apex:include was the original attempt at re-using content between Visualforce pages - its been superseded by components as they are properly re-usable as discrete standalone items.

Doug Chasman, the architect of Visualforce, posted the following on the developer forums in 2008 in response to a question regarding problems with apex:include:

Why are you using apex:include instead of just creating a custom component? apex:include predates custom components and is only still around for backward compatibility. A custom component has a well defined mechanism for specifying the inputs to the included content via attributes and also has the added advantage of passing objects and expressions instead of just query params/name value pairs...

(You can read the original post here)

One reason you might want to use apex:include is that if the main page and the included page use the same controller, they will share the same instance of that controller, and can influence each other's behaviour. I wouldn't recommend it though, as it can make the page structure and effects of changing code quite difficult to understand.

As an aside, composition templates are a way to provide a bunch of boilerplate content and functionality across a set of pages, while allowing each page to inject some custom content into certain areas. The poster child use case for this is a web site where each page injects its specific content into the main body, while the header/sidebar etc is provided by the template.

TL;DR - always use components over apex:include


While I don't have a good justification behind this, at DF 2011 tuning VF Pages for Performance, the product managers had a blanket "Don't use apex:include" it has performance issues.

Given that components have a superset of functionality (include doesn't have parameters), I'd suggest just always using components and call it a day.

  • Thanks for sharing, @Ralph. Would you happen to have a link to that presentation? I searched YouTube but the only ones that came up seem to be from Dreamforce '13.
    – Marty C.
    Jul 1, 2014 at 12:53
  • Sorry I don't, but the DF'13 ones would likely be better than the DF'11 since the content would be fresher. The comment I was referring to wasn't in the presentation it was part of the followup Q&A with the crowd, so wouldn't be in the presentation. Jul 1, 2014 at 20:47
  • I found a doc about optimizing Visualforce, but it did not mention apex:include. It did mention avoiding apex:includescript
    – snugsfbay
    Jul 1, 2014 at 23:17

Here's a great description from Salesforce: https://www.salesforce.com/us/developer/docs/pages/Content/pages_templates_intro.htm

  • Thanks, @snugsfbay. Oddly enough, the same blurb in that page about apex:include I think can also be said of apex:component.
    – Marty C.
    Jul 1, 2014 at 12:44
  • For me, the different tags help provide structure. So my Template provides a framework and uses composition to know where to insert sections of other pages to provide content and my pages use components for subsections that may access specific sObject data. I think I only use include for extra CSS or when I have pasted a web-to-lead or web-to-case auto-generated HTML page into a VF page that I include elsewhere (back in the days before field sets).
    – snugsfbay
    Jul 1, 2014 at 13:37
  • Hello, @snugsfbay, I agree with you 100% about using templates, which leverage apex:insert, apex:composition and apex:define. However, I believe apex:include is something that's unrelated to templates.
    – Marty C.
    Jul 1, 2014 at 18:25
  • The doc I linked above is titled "Templating in Visualforce" or something like that and describes using include in templates. So it is related to templates if you want to use it there in the way they document.
    – snugsfbay
    Jul 1, 2014 at 23:15
  • Here's another Salesforce doc from the "Templating with Visualforce" section of Visualforce online reference which suggests reserving apex:component for code (when a page refers to one sObject type and you need to bring in data from another sObject type, for example): salesforce.com/us/developer/docs/pages/Content/…
    – snugsfbay
    Jul 1, 2014 at 23:41

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .