apex:dataTable

An HTML table that’s defined by iterating over a set of data, displaying information about one item of data per row. The body of the <apex:dataTable> contains one or more column components that specify what information should be displayed for each item of data. The data set can include up to 1,000 items, or 10,000 items when the page is executed in read-only mode.

For Visualforce pages running API version 20.0 or higher, an <apex:repeat> tag can be contained within this component to generate columns.

See also: <apex:panelGrid>

This component supports HTML pass-through attributes using the “html-” prefix. Pass-through attributes are attached to the generated table’s <tbody> tag.

Example 

1<!-- For this example to render fully, associate the page
2with a valid account record in the URL.
3For example: https://MyDomain_login_URL/apex/myPage?id=001D000000IRt53 -->
4
5<!-- Page: -->
6
7<apex:page controller="dataTableCon" id="thePage">
8    <apex:dataTable value="{!accounts}" var="account" id="theTable"
9        rowClasses="odd,even" styleClass="tableClass">
10        <apex:facet name="caption">table caption</apex:facet>
11        <apex:facet name="header">table header</apex:facet>
12        <apex:facet name="footer">table footer</apex:facet>
13
14        <apex:column>
15            <apex:facet name="header">Name</apex:facet>
16            <apex:facet name="footer">column footer</apex:facet>
17            <apex:outputText value="{!account.name}"/>
18        </apex:column>
19
20        <apex:column>
21            <apex:facet name="header">Owner</apex:facet>
22            <apex:facet name="footer">column footer</apex:facet>
23            <apex:outputText value="{!account.owner.name}"/>
24        </apex:column>
25
26    </apex:dataTable>
27</apex:page>
28
29/*** Controller: ***/
30
31public class dataTableCon {
32
33    List<Account> accounts;
34
35    public List<Account> getAccounts() {
36        if(accounts == null)
37            accounts = [SELECT name, owner.name FROM account LIMIT 10];
38        return accounts;
39    }
40
41}

The example above renders the following HTML:

1<table class="tableClass" id="thePage:theTable" border="0" cellpadding="0" cellspacing="0">
2
3    <colgroup span="2"></colgroup>
4    <caption>table caption</caption>
5    <thead>
6        <tr>
7            <td colspan="2" scope="colgroup">table header</td>
8        </tr>
9
10        <tr>
11            <td scope="col">Name</td>
12            <td scope="col">Owner</td>
13        </tr>
14    </thead>
15
16    <tfoot>
17        <tr>
18            <td scope="col">column footer</td>
19            <td scope="col">column footer</td>
20        </tr>
21        <tr>
22            <td colspan="2" scope="colgroup">table footer</td>
23        </tr>
24    </tfoot>
25
26    <tbody>
27        <tr class="odd">
28            <td>Bass Manufacturing</td>
29            <td>Doug Chapman</td>
30        </tr>
31
32        <tr class="even">
33            <td>Ball Corp</td>
34            <td>Alan Ball</td>
35        </tr>
36
37        <tr class="odd">
38            <td>Wessler Co.</td>
39            <td>Jill Wessler</td>
40        </tr>
41    </tbody>
42
43</table>

Attributes 

Attribute NameAttribute TypeDescriptionRequired?API VersionAccess
alignStringThe position of the rendered HTML table with respect to the page. Possible values include “left”, “center”, or “right”. If left unspecified, this value defaults to “left”. 10.0global
bgcolorStringThe background color of the rendered HTML table. 10.0global
borderStringThe width of the frame around the rendered HTML table, in pixels. 10.0global
captionClassStringThe style class used to display the caption for the rendered HTML table, if a caption facet is specified. This attribute is used primarily to designate which CSS styles are applied when using an external CSS stylesheet. 10.0global
captionStyleStringThe style used to display the caption for the rendered HTML table, if a caption facet is specified. This attribute is used primarily for adding inline CSS styles. 10.0global
cellpaddingStringThe amount of space between the border of each table cell and its contents. If the value of this attribute is a pixel length, all four margins are this distance from the contents. If the value of the attribute is a percentage length, the top and bottom margins are equally separated from the content based on a percentage of the available vertical space, and the left and right margins are equally separated from the content based on a percentage of the available horizontal space. 10.0global
cellspacingStringThe amount of space between the border of each table cell and the border of the other cells surrounding it and/or the table’s edge. This value must be specified in pixels or percentage. 10.0global
columnClassesStringA comma-separated list of one or more classes associated with the table’s columns, used primarily to designate which CSS styles are applied when using an external CSS stylesheet. If more than one class is specified, the classes are applied in a repeating fashion to all columns. For example, if you specify columnClasses=“classA, classB”, then the first column is styled with classA, the second column is styled with classB, the third column is styled with classA, the fourth column is styled with classB, and so on. 10.0global
columnsIntegerThe number of columns in this table. 10.0global
columnsWidthStringA comma-separated list of the widths applied to each table column. Values can be expressed as pixels (for example, columnsWidth=“100px, 100px”). 10.0global
dirStringThe direction in which the generated HTML component should be read. Possible values include “RTL” (right to left) or “LTR” (left to right). 10.0global
firstIntegerThe first element in the iteration visibly rendered in the table, where 0 is the index of the first element in the set of data specified by the value attribute. For example, if you did not want to display the first two elements in the set of records specified by the value attribute, set first=“2”. 10.0global
footerClassStringThe style class used to display the footer (bottom row) for the rendered HTML table, if a footer facet is specified. This attribute is used primarily to designate which CSS styles are applied when using an external CSS stylesheet. 10.0global
frameStringThe borders drawn for this table. Possible values include “none”, “above”, “below”, “hsides”, “vsides”, “lhs”, “rhs”, “box”, and “border”. If not specified, this value defaults to “border”. 10.0global
headerClassStringThe style class used to display the header for the rendered HTML table, if a header facet is specified. This attribute is used primarily to designate which CSS styles are applied when using an external CSS stylesheet. 10.0global
idStringAn identifier that allows the dataTable component to be referenced by other components in the page. 10.0global
langStringThe base language for the generated HTML output, for example, “en” or “en-US”. For more information on this attribute, see the W3C specifications. 10.0global
onclickStringThe JavaScript invoked if the onclick event occurs–that is, if the user clicks the data table. 10.0global
ondblclickStringThe JavaScript invoked if the ondblclick event occurs–that is, if the user clicks the data table twice. 10.0global
onkeydownStringThe JavaScript invoked if the onkeydown event occurs–that is, if the user presses a keyboard key. 10.0global
onkeypressStringThe JavaScript invoked if the onkeypress event occurs–that is, if the user presses or holds down a keyboard key. 10.0global
onkeyupStringThe JavaScript invoked if the onkeyup event occurs–that is, if the user releases a keyboard key. 10.0global
onmousedownStringThe JavaScript invoked if the onmousedown event occurs–that is, if the user clicks a mouse button. 10.0global
onmousemoveStringThe JavaScript invoked if the onmousemove event occurs–that is, if the user moves the mouse pointer. 10.0global
onmouseoutStringThe JavaScript invoked if the onmouseout event occurs–that is, if the user moves the mouse pointer away from the data table. 10.0global
onmouseoverStringThe JavaScript invoked if the onmouseover event occurs–that is, if the user moves the mouse pointer over the data table. 10.0global
onmouseupStringThe JavaScript invoked if the onmouseup event occurs–that is, if the user releases the mouse button. 10.0global
onRowClickStringThe JavaScript invoked if the onRowClick event occurs–that is, if the user clicks a row in the data table. 10.0global
onRowDblClickStringThe JavaScript invoked if the onRowDblClick event occurs–that is, if the user clicks a row in the data table twice. 10.0global
onRowMouseDownStringThe JavaScript invoked if the onRowMouseDown event occurs–that is, if the user clicks a mouse button in a row of the data table. 10.0global
onRowMouseMoveStringThe JavaScript invoked if the onRowMouseMove event occurs–that is, if the user moves the mouse pointer over a row of the data table. 10.0global
onRowMouseOutStringThe JavaScript invoked if the onRowMouseOut event occurs–that is, if the user moves the mouse pointer away from a row in the data table. 10.0global
onRowMouseOverStringThe JavaScript invoked if the onRowMouseOver event occurs–that is, if the user moves the mouse pointer over a row in the data table. 10.0global
onRowMouseUpStringThe JavaScript invoked if the onRowMouseUp event occurs–that is, if the user releases the mouse button over a row in the data table. 10.0global
renderedBooleanA Boolean value that specifies whether the component is rendered on the page. If not specified, this value defaults to true. 10.0global
rowClassesStringA comma-separated list of one or more classes associated with the table’s rows, used primarily to designate which CSS styles are applied when using an external CSS stylesheet. If more than one class is specified, the classes are applied in a repeating fashion to all rows. For example, if you specify columnRows=“classA, classB”, then the first row is styled with classA, the second row is styled with classB, the third row is styled with classA, the fourth row is styled with classB, and so on. 10.0global
rowsIntegerThe number of rows in this table. 10.0global
rulesStringThe borders drawn between cells in the table. Possible values include “none”, “groups”, “rows”, “cols”, and “all”. If not specified, this value defaults to “none”. 10.0global
styleStringThe style used to display the dataTable component, used primarily for adding inline CSS styles. 10.0global
styleClassStringThe style class used to display the dataTable component, used primarily to designate which CSS styles are applied when using an external CSS stylesheet. 10.0global
summaryStringA summary of the table’s purpose and structure for Section 508 compliance. 10.0global
titleStringThe text to display as a tooltip when the user’s mouse pointer hovers over this component. 10.0global
valueObjectThe collection of data displayed in the table.Yes10.0global
varStringThe name of the variable that represents one element in the collection of data specified by the value attribute. You can then use this variable to display the element itself in the body of the dataTable component tag.Yes10.0global
widthStringThe width of the entire table, expressed either as a relative percentage to the total amount of available horizontal space (for example, width=“80%”), or as the number of pixels (for example, width=“800px”). 10.0global

Facets 

Facet NameDescriptionAPI Version
captionThe components that appear in the caption for the table. Note that the order in which a caption facet appears in the body of a dataTable component doesn’t matter, because any facet with name=“caption” will control the appearance of the table’s caption.10.0
footerThe components that appear in the footer row for the table. Note that the order in which a footer facet appears in the body of a dataTable component doesn’t matter, because any facet with name=“footer” will control the appearance of the final row in the table.10.0
headerThe components that appear in the header row for the table. Note that the order in which a header facet appears in the body of a dataTable component doesn’t matter, because any facet with name=“header” will control the appearance of the first row in the table.10.0

See Also