apex:include vs. Visualforce component, when and why?

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.


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