Hide

Visualization: Table

Overview

A table that can be sorted and paged. Table cells can be formatted using format strings, or by directly inserting HTML as cell values. Numeric values are right-aligned; boolean values are displayed as check marks. Users can select single rows either with the keyboard or the mouse. Users can sort rows by clicking on column headers. The header row remains fixed as the user scrolls. The table fires a number of events corresponding to user interaction.

Example

<html>
  <head>
    <script type="text/javascript" src="https://www.google.com/jsapi"></script>
    <script type="text/javascript">
      google.load("visualization", "1", {packages:["table"]});
      google.setOnLoadCallback(drawTable);

      function drawTable() {
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Name');
        data.addColumn('number', 'Salary');
        data.addColumn('boolean', 'Full Time Employee');
        data.addRows([
          ['Mike',  {v: 10000, f: '$10,000'}, true],
          ['Jim',   {v:8000,   f: '$8,000'},  false],
          ['Alice', {v: 12500, f: '$12,500'}, true],
          ['Bob',   {v: 7000,  f: '$7,000'},  true]
        ]);

        var table = new google.visualization.Table(document.getElementById('table_div'));

        table.draw(data, {showRowNumber: true});
      }
    </script>
  </head>
  <body>
    <div id="table_div"></div>
  </body>
</html>

Loading

The google.load package name is "table".

  google.load('visualization', '1', {packages: ['table']});

The visualization's class name is google.visualization.Table.

  var visualization = new google.visualization.Table(container);

Data Format

The DataTable is converted into a corresponding HTML table, with each row/column in the DataTable converted into a row/column in the HTML table. Each column must be of the same data type, and all standard visualization data types are supported (string, boolean, number, etc).

Custom Properties

You can assign the following custom properties to data table elements, using the setProperty() method of DataTable.

Property Name Applies To Description
className Cell A string class name to assign to an individual cell. Use this to assign CSS styling to individual cells.
style Cell A style string to assign inline to the cell. This will override CSS class styles applied to that cell. You must set the property allowHtml=true for this to work. Example: 'border: 1px solid green;'.

Example

dataTable.setCell(22, 2, 15, 'Fifteen', {style: 'font-style:bold; font-size:22px;'});

Configuration Options

Name
allowHtml

If set to true, formatted values of cells that include HTML tags will be rendered as HTML. If set to false, most custom formatters will not work properly.

Type: boolean
Default: false
alternatingRowStyle

Determines if alternating color style will be assigned to odd and even rows.

Type: boolean
Default: true
cssClassNames

An object in which each property name describes a table element, and the property value is a string, defining a class to assign to that table element. Use this property to assign custom CSS to specific elements of your table. To use this property, assign an object, where the property name specifies the table element, and the property value is a string, specifying a class name to assign to that element. You must then define a CSS style for that class on your page. The following property names are supported:

  • headerRow - Assigns a class name to the table header row (<tr> element).
  • tableRow - Assigns a class name to the non-header rows (<tr> elements).
  • oddTableRow - Assigns a class name to odd table rows (<tr> elements). Note: the alternatingRowStyle option must be set to true.
  • selectedTableRow - Assigns a class name to the selected table row (<tr> element).
  • hoverTableRow - Assigns a class name to the hovered table row (<tr> element).
  • headerCell - Assigns a class name to all cells in the header row (<td> element).
  • tableCell - Assigns a class name to all non-header table cells (<td> element).
  • rowNumberCell - Assigns a class name to the cells in the row number column (<td> element). Note: the showRowNumber option must be set to true.

Example: var cssClassNames = {headerRow: 'bigAndBoldClass',
hoverTableRow: 'highlightClass'};

Note: In CSS, some elements override others. For instance, if you specify a background color for a <tr> element and a <td> element, the latter takes precedence over the former. Be sure to specify all relevant CSS styles in cssClassNames to avoid conflicts.

Type: object
Default: null
firstRowNumber

The row number for the first row in the dataTable. Used only if showRowNumber is true.

Type: number
Defaul: 1
frozenColumns

The number of columns from the left that will be frozen. These columns will remain in place when scrolling the remaining columns horizontally. If showRowNumber is false, setting frozenColumns to 0 will appear the same as if set to null, but if showRowNumber is set to true, the row number column will be frozen.

Type: number
Default: null
height

Sets the height of the visualization's container element. You can use standard HTML units (for example, '100px', '80em', '60'). If no units are specified the number is assumed to be pixels. If not specified, the browser will adjust the height automatically to fit the table, shrinking as much as possible in the process; if set smaller than the height required, the table will add a vertical scroll bar (the header row is also frozen). If set to '100%', the table will expand as much as possible into the container element.

Type: string
Default: automatic
page

If and how to enable paging through the data. Choose one of the following string values:

  • 'enable' - The table will include page-forward and page-back buttons. Clicking on these buttons will perform the paging operation and change the displayed page. You might want to also set the pageSize option.
  • 'event' - The table will include page-forward and page-back buttons, but clicking them will trigger a 'page' event and will not change the displayed page. This option should be used when the code implements its own page turning logic. See the TableQueryWrapper example for an example of how to handle paging events manually.
  • 'disable' - [Default] Paging is not supported.
  • Type: string
    Default: 'disable'
pageSize

The number of rows in each page, when paging is enabled with the page option.

Type: number
Default: 10
pagingButtons

Sets a specified option for the paging buttons. The options are as follows:

  • 'both' - enable prev and next buttons
  • 'prev' - only prev button is enabled
  • 'next' - only next button is enabled
  • 'auto' - the buttons are enabled according to the current page. On the first page only next is shown. On the last page only prev is shown. Otherwise both are enabled.
  • number - the number of paging buttons to show. This explicit number will override computed number from pageSize.
Type: string or number
Default: 'auto'
rtlTable

Adds basic support for right-to-left languages (such as Arabic or Hebrew) by reversing the column order of the table, so that column zero is the rightmost column, and the last column is the leftmost column. This does not affect the column index in the underlying data, only the order of display. Full bi-directional (BiDi) language display is not supported by the table visualization even with this option. This option will be ignored if you enable paging (using the page option), or if the table has scroll bars because you have specified height and width options smaller than the required table size.

Type: boolean
Default: false
scrollLeftStartPosition

Sets the horizontal scrolling position, in pixels, if the table has horizontal scroll bars because you have set the width property. The table will open scrolled that many pixels past the leftmost column.

Type: number
Default: 0
showRowNumber

If set to true, shows the row number as the first column of the table.

Type: boolean
Default: false
sort

If and how to sort columns when the user clicks a column heading. If sorting is enabled, consider setting the sortAscending and sortColumn properties as well. Choose one of the following string values:

  • 'enable' - [Default] Users can click on column headers to sort by the clicked column. When users click on the column header, the rows will be automatically sorted, and a 'sort' event will be triggered.
  • 'event' - When users click on the column header, a 'sort' event will be triggered, but the rows will not be automatically sorted. This option should be used when the page implements its own sort. See the TableQueryWrapper example for an example of how to handle sorting events manually.
  • 'disable' - Clicking a column header has no effect.
Type: string
Default: 'enable'
sortAscending

The order in which the initial sort column is sorted. True for ascending, false for descending. Ignored if sortColumn is not specified.

Type: boolean
Default: true
sortColumn

An index of a column in the data table, by which the table is initially sorted. The column will be marked with a small arrow indicating the sort order.

Type: number
Default: -1
startPage

The first table page to display. Used only if page is in mode enable/event.

Type: number
Default: 0
width

Sets the width of the visualization's container element. You can use standard HTML units (for example, '100px', '80em', '60'). If no units are specified the number is assumed to be pixels. If not specified, the browser will adjust the width automatically to fit the table, shrinking as much as possible in the process; if set smaller than the width required, the table will add a horizontal scroll bar. If set to '100%', the table will expand as much as possible into the container element.

Type: string
Default: automatic

Methods

Method
draw(data, options)

Draws the table.

Return Type: none
getSelection()

Standard getSelection implementation. Selection elements are all row elements. Can return more than one selected row. The row indexes in the selection object refer to the original data table regardless of any user interaction (sort, paging, etc.).

Note that the selection(s) toggle: clicking a cell the first time selects it; clicking the cell again deselects it, resulting in a selection event, but no selected items in the retrieved selection object.

Return Type: Array of selection elements
getSortInfo()

Call this method to retrieve information about the current sort stateof a table that has been sorted (typically by the user, who has clicked on a column heading to sort the rows by a specific column). If you have disabled sorting, this method will not work.

If you have not sorted data in code, or the user has not sorted data by selecting code, the default sort values will be returned.

Return Type: An object with the following properties:
  • column - (number) Index of the column by which the table is sorted.
  • ascending - (boolean) true if the sort is ascending, false if descending.
  • sortedIndexes - (numeric array) Array of numbers, where the index in the array is the row number as sorted (in the visible table), and the value is the index of that row in the underlying (unsorted) data table.
setSelection(selection)

Standard setSelection() implementation, but can only select entire rows, or multiple rows. The row indexes in the selection object refer to the original data table regardless of any user interaction (sort, paging, etc.).

Return Type: none
clearChart()

Clears the chart, and releases all of its allocated resources.

Return Type: none

Events

Name
select

Standard select event, but only entire rows can be selected.

Properties: None
page

Triggered when users click on a page navigation button.

Properties: page: Number. The index of page to navigate to.
sort

Triggered when users click on a column header, and the sort option is not 'disable'.

Properties: An object with the following properties:
  • column - (number) Index of the column by which the table is sorted.
  • ascending - (boolean) true if the sort is ascending, false if descending.
  • sortedIndexes - (numeric array) Array of numbers, wherethe index in the array is the row number as sorted (in the visible table), and the value is the index of that row in the underlying (unsorted) data table.
ready

The chart is ready for external method calls. If you want to interact with the chart, and call methods after you draw it, you should set up a listener for this event before you call the draw method, and call them only after the event was fired.

Properties: None

Formatters

Note: The table visualization has a set of formatter objects that have been superceded by generic formatters, which behave the same way, but can be used in any visualization.

The following table shows the legacy table formatter and its equivalent generic formatter. You should use the generic formatter when writing new code.

Table Formatter
TableArrowFormat google.visualization.ArrowFormat
TableBarFormat google.visualization.BarFormat
TableColorFormat google.visualization.ColorFormat
TableDateFormat google.visualization.DateFormat
TableNumberFormat google.visualization.NumberFormat
TablePatternFormat google.visualization.PatternFormat

Important: Formatters often use HTML to format their text; therefore, you should set the allowHtml option to true.

Data Policy

All code and data are processed and rendered in the browser. No data is sent to any server.