1. [Overview](https://developers.google.com/chart/interactive/docs/gallery/timeline#Overview) 2. [A simple example](https://developers.google.com/chart/interactive/docs/gallery/timeline#SimpleExample) 3. [Labeling the bars](https://developers.google.com/chart/interactive/docs/gallery/timeline#LabelingBars) 4. [An advanced example](https://developers.google.com/chart/interactive/docs/gallery/timeline#AdvancedExample) 5. [Putting bars on one row](https://developers.google.com/chart/interactive/docs/gallery/timeline#BarsOneRow) 6. [Changing the fonts](https://developers.google.com/chart/interactive/docs/gallery/timeline#ChangingFonts) 7. [Controlling the colors](https://developers.google.com/chart/interactive/docs/gallery/timeline#ControllingColors) 8. [Overlapping gridlines](https://developers.google.com/chart/interactive/docs/gallery/timeline#GridLines) 9. [Customizing tooltips](https://developers.google.com/chart/interactive/docs/gallery/timeline#Tooltips) 10. [Loading](https://developers.google.com/chart/interactive/docs/gallery/timeline#Loading) 11. [Data format](https://developers.google.com/chart/interactive/docs/gallery/timeline#Data_Format) 12. [Configuration options](https://developers.google.com/chart/interactive/docs/gallery/timeline#Configuration_Options) 13. [Methods](https://developers.google.com/chart/interactive/docs/gallery/timeline#Methods) 14. [Events](https://developers.google.com/chart/interactive/docs/gallery/timeline#Events) 15. [Data policy](https://developers.google.com/chart/interactive/docs/gallery/timeline#Data_Policy) ## Overview A *timeline* is a chart that depicts how a set of resources are used over time. If you're managing a software project and want to illustrate who is doing what and when, or if you're organizing a conference and need to schedule meeting rooms, a timeline is often a reasonable visualization choice. One popular type of timeline is the *Gantt chart*. **Note:** In JavaScript Date objects, months are indexed starting at zero and go up through eleven, with January being month 0 and December being month 11. If your timeline seems off by a month, this is most likely why. For more information, see the [Dates and Times](https://developers.google.com/chart/interactive/docs/datesandtimes) page. ## A simple example Let's say you want to plot when American presidents served their terms. Here, the "resources" are the presidents, and we can plot each president's term as a bar: Hovering over a bar brings up a tooltip with more detailed information. \

``` Google Charts timelines are customizable, and in the following examples we'll show you some common ways to tailor the appearance of your timelines. ## Labeling the bars In addition to the row labels ("Washington", "Adams", "Jefferson" above) you can label individual bars. Here, we change the row labels to simple numbers and place each president's name on his bar. In this code, we've inserted a new column into our data to hold the bar labels: the full name of each president. When there are four columns in a timeline `dataTable`, the first is interpreted as the row label, the second as the bar label, and the third and fourth as start and end. ```

``` Our new row labels above aren't very informative, so let's remove them with the timeline `showRowLabels` option. By default, `showRowLabels` is `true`. Setting it to `false` removes the row labels: ```

``` ## An advanced example To make our timeline more complex, let's add vice presidents and secretaries of state to our chart. John Adams was vice president before he became president, and Thomas Jefferson was secretary of state, then vice president, and finally president. In timelines, a resource will have the same color even when it appears on multiple rows, so in the following chart each person is represented with a consistent color. Some secretaries of state served for very short times, so this chart is a good test of labeling. When a label is too big for the bar, it's abbreviated or eliminated, depending on the bar size. Users can always hover over the bar to get tooltip information. The timeline will lay out the rows in order---president on top of vice president on top of secretary of state---because that's the order that they appear in the code below. However, the layout of the bars is determined solely by the start and end times, so swapping two secretaries of state or two presidents in the `dataTable` has no effect on the chart. ```

``` ## Putting bars on one row [Unlike popes](http://en.wikipedia.org/wiki/Western_Schism), there can only be one U.S. president at a time, so if we label all of our rows as "President", the timeline will combine the three rows of our first chart into one row for a cleaner presentation. You can control this behavior with the `groupByRowLabel` option. Here's the default behavior: Now let's set `groupByRowLabel` to `false` and split the one row into three: The code to turn off grouping: ```

``` ## Controlling the colors By default, Google Charts chooses colors optimized for aesthetics and readability (including users with visual disabilities). You can tailor the default behavior with the `colorByRowLabel`, `singleColor`, `backgroundColor` and `colors` options. The `colorByRowLabel` option colors all bars on the same row the same. This can be a good choice when there are gaps between your bars. `colorByRowLabel` defaults to `false`, so here we override that and set it to `true`. ```

``` If you want all bars the same color regardless of what row they're on, use the `singleColor` option: In the code below, `singleColor` is set to a hex value to color all the bars light green: ```

``` You can control the background color of the rows with the `backgroundColor` option: The `backgroundColor` is specified as a hex value. Here, we pair it with `colorByRowLabel` to show tracks in a conference: ```

``` Then, to set the background color to alternating or non-alternating by row index, use the `alternatingRowStyle` option (active v51+): ```

``` If you want to control the colors of individual bars, use the `colors` option: `colors` takes an array of hex values, which are applied to the bars in order: ```

``` If your chart requires more colors than listed, the chart will behave as though `singleColor` is set to the first color in the list. (This is true for all Google Charts, not just timelines.) Another way of controlling the colors of individual bars is to use a column with the [style role](https://developers.google.com/chart/interactive/docs/roles#stylerole). The code to add and populate a style column: ```

``` ## Changing the fonts You can choose the typeface and font for the labels of each row with `rowLabelStyle`, and for the labels on each bar with `barLabelStyle`. Both are demonstrated below. Note: Be sure to choose typefaces that your users' browsers will be able to render. ```

``` You can't set the color of `barLabel` text. ## Overlapping gridlines Google Charts makes tiny adjustments to bar endpoints to avoid obscuring timeline gridlines. To prevent this behavior, set the `avoidOverlappingGridLines` option to `false`. To illustrate the effect, here are two examples, the first with an overlapped gridline and the second without. Here's code that overlaps gridlines: ```

``` ## Customizing tooltips You can customize what users see when they hover over the bars of a timeline by adding a tooltip column into a five-column datatable. To provide non-default tooltips, every row of your datatable must have all five columns (row label, bar label, tooltip, start, and end): Hovering over a bar brings up a tooltip with the text defined in the third column. In this chart, we have to set the second column to dummy values (here, `null`) so that our tooltips can exist in the third column. \ ``` ## Loading The `google.charts.load` package name is `timeline`: ``` google.charts.load("current", {packages: ["timeline"]}); ``` The visualization's class name is `google.visualization.Timeline`: ``` var visualization = new google.visualization.Timeline(container); ``` ## Data format **Rows:** Each row in the table represents a timeline bar. **Columns:** | | Column 0 | Column 1 | Column 2 | Column 3 | Column 4 | | Purpose: | Row label | Bar label (optional) | Tooltip (optional) | Start | End | | Data Type: | string | string | string | number or date | number or date | | Role: | data | data | [tooltip](https://developers.google.com/chart/interactive/docs/roles#tooltiprole) | data | data | |---|---|---|---|---|---| ## Configuration options | Name || |---|---| | alternatingRowStyle | Whether the chart should alternate background color by row index (i.e., tint background color of even-indexed rows a darker hue). If false, chart background will be one uniform color. If true, chart background will alternate tint by row index. (Note: active v51+) **Type:** boolean **Default:** true | | avoidOverlappingGridLines | Whether display elements (e.g., the bars in a timeline) should obscure grid lines. If false, grid lines may be covered completely by display elements. If true, display elements may be altered to keep grid lines visible. **Type:** boolean **Default:** true | | backgroundColor | The background color for the main area of the chart. Can be either a simple HTML color string, for example: `'red'` or `'#00cc00'`, or an object with the following properties. **Type:** string or object **Default:** 'white' | | colors | The colors to use for the chart elements. An array of strings, where each element is an HTML color string, for example: `colors:['red','#004411']`. **Type:** Array of strings **Default:** default colors | | enableInteractivity | Whether the chart throws user-based events or reacts to user interaction. If false, the chart will not throw 'select' or other interaction-based events (but *will* throw ready or error events), and will not display hovertext or otherwise change depending on user input. **Type:** boolean **Default:** true | | fontName | The default font face for all text in the chart. You can override this using properties for specific chart elements. **Type:** string **Default:** 'Arial' | | fontSize | The default font size, in pixels, of all text in the chart. You can override this using properties for specific chart elements. **Type:** number **Default:** automatic | | forceIFrame | Draws the chart inside an inline frame. (Note that on IE8, this option is ignored; all IE8 charts are drawn in i-frames.) **Type:** boolean **Default:** false | | height | Height of the chart, in pixels. **Type:** number **Default:** height of the containing element | | timeline.barLabelStyle | An object that specifies the bar label text style. It has this format: ``` {fontName: , fontSize: } ``` Also see `fontName` and `fontSize` in this table. **Type:** object **Default:** null | | timeline.colorByRowLabel | If set to true, colors every bar on the row the same. The default is to use one color per bar label. **Type:** boolean **Default:** false | | timeline.groupByRowLabel | If set to false, creates one row for every `dataTable` entry. The default is to collect bars with the same row label into one row. **Type:** boolean **Default:** true | | timeline.rowLabelStyle | An object that specifies the row label text style. It has this format: ``` {color: , fontName: , fontSize: } ``` The `color` can be any HTML color string, for example `'red'` or `'#00cc00'` Also see `fontName` and `fontSize` in this table. **Type:** object **Default:** null | | timeline.showBarLabels | If set to false, omits bar labels. The default is to show them. **Type:** boolean **Default:** true | | timeline.showRowLabels | If set to false, omits row labels. The default is to show them. **Type:** boolean **Default:** true | | timeline.singleColor | Colors all bars the same. Specified as a hex value (e.g., '#8d8'). **Type:** string **Default:** null | | tooltip.isHtml | Set to `false` to use SVG-rendered (rather than HTML-rendered) tooltips. See [Customizing Tooltip Content](https://developers.google.com/chart/interactive/docs/customizing_tooltip_content) for more details. **Note:** customization of the HTML tooltip content via the [tooltip column data role](https://developers.google.com/chart/interactive/docs/roles#tooltiprole) is **not** supported by the [Bubble Chart](https://developers.google.com/chart/interactive/docs/gallery/bubblechart) visualization. **Type:** boolean **Default:** true | | tooltip.trigger | The user interaction that causes the tooltip to be displayed: - 'focus' - The tooltip will be displayed when the user hovers over the element. - 'none' - The tooltip will not be displayed. **Type:** string **Default:** 'focus' | | width | Width of the chart, in pixels. **Type:** number **Default:** width of the containing element | ## Methods | Method || |---|---| | `draw(data, options)` | Draws the chart. The chart accepts further method calls only after the [`ready`](https://developers.google.com/chart/interactive/docs/gallery/timeline#Events)event is fired. [`Extended description`](https://developers.google.com/chart/interactive/docs/reference#visdraw). **Return Type:** none | | `clearChart()` | Clears the chart, and releases all of its allocated resources. **Return Type:** none | | `getSelection()` | Returns an array of the selected chart entities. Selectable entities are bars, legend entries and categories. For this chart, only one entity can be selected at any given moment. [`Extended description`](https://developers.google.com/chart/interactive/docs/reference#visgetselection). **Return Type:** Array of selection elements | ## Events | Name || |---|---| | `error` | Fired when an error occurs when attempting to render the chart. **Properties:** id, message | | `onmouseover` | Fired when the user mouses over a visual entity. Passes back the row and column indices of the corresponding data table element. A bar correlates to a cell in the data table, a legend entry to a column (row index is null), and a category to a row (column index is null). **Properties:** row, column | | `onmouseout` | Fired when the user mouses away from a visual entity. Passes back the row and column indices of the corresponding data table element. A bar correlates to a cell in the data table, a legend entry to a column (row index is null), and a category to a row (column index is null). **Properties:** row, column | | `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 | | `select` | Fired when the user clicks a visual entity. To learn what has been selected, call [`getSelection()`](https://developers.google.com/chart/interactive/docs/gallery/timeline#Methods). **Properties:** none | ## Data policy All code and data are processed and rendered in the browser. No data is sent to any server.