Setting Custom HTML Attributes on Visualforce Components

You can add arbitrary attributes to many Visualforce components that are “passed through” to the rendered HTML. This is useful, for example, when using Visualforce with JavaScript frameworks, such as jQuery Mobile, AngularJS, and Knockout, which use data-* or other attributes as hooks to activate framework functions.
Pass-through attributes can also be used to improve usability with HTML5 features such as placeholder “ghost” text, pattern client-side validation, and title help text attributes.

The behavior of HTML5 features is determined by the user’s browser, not Visualforce, and varies considerably from browser to browser. If you want to use these features, test early and often on every browser and device you plan to support.

Important

To add a pass-through attribute to, for example, an <apex:outputPanel> component, prefix the attribute with “html-” and set the attribute value as normal.
<apex:page showHeader="false" standardStylesheets="false" doctype="html-5.0">

    <apex:outputPanel layout="block" html-data-role="panel" html-data-id="menu">
        <apex:insert name="menu"/>    
    </apex:outputPanel>

    <apex:outputPanel layout="block" html-data-role="panel" html-data-id="main">
        <apex:insert name="main"/>    
    </apex:outputPanel>

</apex:page>
This produces the following HTML output.
<!DOCTYPE HTML>
<html>
<head> ... </head>
<div id="..." data-id="menu" data-role="panel">
    <!-- contents of menu -->
</div>

<div id="..." data-id="main" data-role="panel">
    <!-- contents of main -->
</div>
</html>
Every attribute that begins with “html-” is passed through to the resulting HTML, with the “html-” removed.

Pass-through attributes that conflict with built-in attributes for the component generate a compilation error.

Note

Pass-through attributes are supported by the following Visualforce components.
  • <apex:column>
  • <apex:commandButton>
  • <apex:commandLink>
  • <apex:component>
  • <apex:dataTable>
  • <apex:form>
  • <apex:iframe>
  • <apex:image>
  • <apex:includeScript>
  • <apex:input>
  • <apex:inputCheckbox>
  • <apex:inputField>
  • <apex:inputHidden>
  • <apex:inputSecret>
  • <apex:inputText>
  • <apex:inputTextarea>
  • <apex:messages>
  • <apex:outputField>
  • <apex:outputLabel>
  • <apex:outputLink>
  • <apex:outputPanel>
  • <apex:outputText>
  • <apex:page>
  • <apex:pageBlock>
  • <apex:pageBlockButtons>
  • <apex:pageBlockSection>
  • <apex:pageBlockSectionItem>
  • <apex:pageBlockTable>
  • <apex:panelBar>
  • <apex:panelBarItem>
  • <apex:panelGrid>
  • <apex:sectionHeader>
  • <apex:selectCheckboxes>
  • <apex:selectList>
  • <apex:selectOption>
  • <apex:selectOptions>
  • <apex:selectRadio>
  • <apex:stylesheet>
  • <apex:tab>
  • <apex:tabPanel>
For additional information about individual components, including the specifics of where pass-through attributes are added to their rendered HTML, see Standard Visualforce Component Reference.
To create HTML markup that can’t be generated using components that support pass-through attributes, combine Visualforce tags with static HTML. For example, to create a jQuery Mobile listview, combine the <apex:repeat> tag with the HTML tags you need.
<ul data-role="listview" data-inset="true" data-filter="true">
    <apex:repeat value="{! someListOfItems}" var="item">
        <li><a href="#">{! item.Name}</a></li>
    </apex:repeat>
</ul>

Pass-through attributes aren’t supported in dynamic Visualforce.