Controls and Dashboards

On this page, you'll see how to combine multiple charts into
dashboards and give users controls to manipulate what data they show.

Overview

Dashboards are a simple way to organize together and manage multiple charts
that share the same underlying data. By using the APIs described in this page, you can free
yourself from the burden of wiring together and coordinating all the charts that are part of
a dashboard.

Dashboards are defined using
google.visualization.Dashboard classes.
Dashboard instances receive a DataTable containing the data to
visualize and take care of drawing and distributing the data to all the charts that are part
of the dashboard.

Controls are user interface widgets (such as category pickers, range sliders,
autocompleters...) you interact with in order to drive the data managed by a dashboard and the
charts that are part of it.

Controls are defined using
google.visualization.ControlWrapper classes.
You can add ControlWrapper instances to a dashboard, where they behave like pipes
and valves in a plumbing system. They collect user input and use the information to decide which
of the data the dashboard is managing should be made available to the charts that are part of it.

Have a look at the following example where a category picker and a range slider are used to
drive the data visualized by a pie chart.

[This section requires a browser that supports JavaScript and iframes.]

Note: The dashboard is interactive. Try operating the controls and see the
chart change in real time.

Using Controls
and Dashboards

Here are the key steps for creating a dashboard and embedding it in your page. You'll find a code
snippet demonstrating all these steps below, followed by detailed information about each step.

Create an HTML skeleton for your dashboard.
Your page must have as many HTML elements as needed to hold every member of a dashboard.
This includes the dashboard itself and all the controls and charts that are part of it.
Typically you'll use a <div> for each one.

Load your libraries. A dashboard requires
only two libraries to be included or loaded on the page: the Google AJAX API and the Google
Visualization controls package.

Prepare your data. You'll need to prepare the data
to visualize; this means either specifying the data yourself in code, or querying a remote site
for data.

Create a dashboard instance. Instantiate your
dashboard by calling its constructor and passing in a reference to the <div> element
that will hold it.

Establish dependencies. Call
bind() on your dashboard and pass in the control and chart instances to let the
dashboard know what to manage. Once a control and chart are bound together, the dashboard
updates the chart to match the constraints the control enforces over the data.

Draw your dashboard. Call draw()
on your dashboard and pass in your data to draw the entire dashboard on the page.

Programmatic changes after draw.
Optionally, after the initial draw you can programmatically drive the controls that are part of
the dashboard, and have the dashboard update the charts in response to that.

Here's a simple example of a page that creates a simple dashboard with a range slider driving a
pie chart. The resulting dashboard is shown below the snippet.

[This section requires a browser that supports JavaScript and iframes.]

1. Create An HTML Skeleton For Your Dashboard

Your page must have as many HTML elements (typically <div>s) to hold both the dashboard
itself and all the controls and charts part of it. When instantiating dashboard, control, and
chart instances, you must pass a reference to their element, so assign an ID to each HTML element.

<!--Div that will hold the dashboard-->
<div id="dashboard_div">
<!--Divs that will hold each control and chart-->
<div id="filter_div"></div>
<div id="chart_div"></div>
</div>

You are free to position each HTML element however you want your dashboard to look.

2. Load Your Libraries

A dashboard requires only two libraries to be included or loaded on the page: the Google AJAX API
and the Google Visualization controls package. The API (in particular,
google.visualization.ChartWrapper) automatically identifies the other packages
needed (for example, gauge if you are using a Gauge chart) and loads them on the fly
without further intervention from you.

You must use google.charts.load() to fetch the control library.

<!--Load the AJAX API-->
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
// Load the Visualization API and the controls package.
// Packages for all the other charts you need will be loaded
// automatically by the system.
google.charts.load('current', {'packages':['corechart', 'controls']});
// Set a callback to run when the Google Visualization API is loaded.
google.charts.setOnLoadCallback(drawDashboard);
function drawDashboard() {
// Everything is loaded. Assemble your dashboard...
}
</script>

3. Prepare Your Data

When the Visualization API has been loaded, google.charts.setOnLoadCallback() will call your
handler function, so you know that all the required helper methods and classes will be ready for
you to start preparing your data.

Dashboards accepts data in a DataTable, the same as charts.

4. Create A Dashboard Instance

After you have created your data, you can instantiate your dashboard object. A dashboard
constructor takes one parameter: a reference to the DOM element in which to draw the dashboard.

Dashboards are exposed as a Javascript class. After instantiating your dashboard, you can perform
a few optional steps such as adding event listeners (for example, to be notified once the
dashboard is 'ready'). Dashboards handle events in the same way charts do, so refer to
Handling Visualization Events or
Displaying Errors Nicely in the chart
section for more information.

When creating ChartWrapper and ControlWrapper instances, do not specify
either the dataTable or the dataSourceUrl parameter. The dashboard
takes care of feeding each one with the appropriate data. However, be sure to specify the
required parameters: chartType and containerId for charts,
controlType and containerId for controls.

A few tips about configuring controls and charts:

You must give all controls a filterColumnIndex
(or filterColumnLabel) to specify which column of your
google.visualization.DataTable the control operates on (in the example above, the
control operates on the column labeled Donuts eaten),

Use the state configuration option on controls to initialize them with an
explicit state when they are first drawn. For example, use this setting to fix the initial
positions of the thumbs of a range slider control.

All the charts that are part of a dashboard share the same underlying dataTable you prepared
in the Prepare Your Data step. However, charts often
require a specific arrangement of columns to display correctly: for example, a pie chart
requires a string column for the label, followed by a number column for the value.

Use the view option while configuring each ChartWrapper instance to
declare which columns are relevant for the chart, as in the following example.

6. Establish Dependencies

Once you have instantiated both the dashboard and all the controls and charts that will be part
it, use the bind() method to tell the dashboard about the dependencies that exist
between controls and charts.

Once a control and chart are bound together, the dashboard updates the chart to match the
constraints the control enforces over the data. In the example dashboard you are building,
the range slider and the pie chart are bound together, so whenever you interact with the former,
the latter updates to display only the data that matches the selected range.

You can bind controls and charts in many different configurations: one-to-one, one-to-many,
many-to-one and many-to-many. Whenever multiple controls are bound to a chart, the dashboard
updates the chart to match the combined constraints enforced by all the bound controls. At the
same time, a control can drive multiple charts concurrently. To specify multiple bindings at the
same time, pass in arrays to the bind() method instead of single instances. You can
also chain multiple bind() calls together. Here are some examples.

7. Draw Your Dashboard

Call the draw() method on the dashboard instance to render the entire dashboard.
The draw() method takes only one parameter: the DataTable
(or DataView) that powers the dashboard.

You should call draw() every time you change the composition of the dashboard
(for example by adding new controls or charts to it) or you change the overall
DataTable that powers it.

The dashboard instance fires a ready event whenever draw() terminates
drawing all the controls and charts that are part of it. An error event is fired if
any of the managed controls or chart fails to draw. To learn more about handling events, see
Handling Events.

Note: You should listen for the ready event before you try to
change the dashboard composition or draw it again.

8. Programmatic Changes After Draw

Once the dashboard completes the initial draw() it will be live and respond
automatically to any action you perform on it (such as changing the selected range of a control
slider that is part of the dashboard).

If you need to programmatically alter the dashboard state, you can do so by operating directly
on the ControlWrapper and ChartWrapper instances that are part of it.
The rule of thumb is to perform any change you need directly on the specific
ControlWrapper (or ChartWrapper) instance: for example, change a
control option or state via setOption() and setState() respectively,
and call its draw() method afterward. The dashboard will then update to match the
requested changes.

The following example shows such a case.

[This section requires a browser that supports JavaScript and iframes.]

API Reference

This section lists the objects exposed by the Controls and Dashboards API, and the standard
methods exposed by all controls.

Dashboard

Represents a collection of collaborating controls and charts that share the same underlying data.

Constructor

Dashboard(containerRef)

containerRef

A reference to a valid container element on the page that will hold the dashboard contents.

Methods

Dashboard exposes the following methods:

Method

Return Type

Description

bind(controls, charts)

google.visualization.Dashboard

Binds one or more Controls to one or more other dashboard participants (either charts or
other controls), so that all of the latter are redrawn whenever any of the former collects
a programmatic or user interaction that affects the data managed by the dashboard. Returns
the dashboard instance itself for chaining multiple bind() calls together.

controls - Either a single one or an array of
google.visualization.ControlWrapper instances defining the controls to bind.

charts - Either a single one or an array of
google.visualization.ChartWrapper instances defining the charts the that
will be driven the by the controls.

Returns an array of the selected visual entities of the charts in the dashboard. The
getSelection() method, when called on the dashboard, returns an aggregate of
all of the selections made on all of the charts within it, allowing for the use of a
single reference when working with chart selections.

Events

The Dashboard object throws the following events. Note that you must call
Dashboard.draw() before any events will be thrown.

Name

Description

Properties

error

Fired when an error occurs when attempting to render the dashboard. One or more of the
controls and charts that are part of the dashboard may have failed rendering.

id, message

ready

The dashboard has completed drawing and is ready to accept changes. All the controls and
charts that are part of the dashboard are ready for external method call and user
interaction. If you want to change the dashboard (or the data it displays) after you draw
it, you should set up a listener for this event before you call the draw
method, and then apply your changes only after the event was fired.

The ready event will also fire:

after the completion of a dashboard refresh triggered by a user or programmatic
interaction with one of the controls,

after a programmatic call to the draw() method of any chart part of the
dashboard.

None

ControlWrapper

A ControlWrapper object is a wrapper around a JSON representation of a configured control
instance. The class exposes convenience methods for defining a dashboard control, drawing it and
programmatically changing its state.

Constructor

ControlWrapper(opt_spec)

opt_spec

[Optional] - Either a JSON object defining the control, or a serialized string version
of that object. The supported properties of the JSON object are shown in the following table.
If not specified, you must set all the appropriate properties using the set... methods
exposed by ControlWrapper.

Property

Type

Required

Default

Description

controlType

String

Required

none

The class name of the control. The google.visualization package name can be
omitted for Google controls. Examples:CategoryFilter,
NumberRangeFilter.

containerId

String

Required

none

The ID of the DOM element on your page that will host the control.

options

Object

Optional

none

An object describing the options for the control. You can use either JavaScript literal
notation, or provide a handle to the object. Example:
"options": {"filterColumnLabel": "Age",
"minValue": 10, "maxValue": 80}

state

Object

Optional

none

An object describing the state of the control. The state collects all the variables that the
user operating the control can affect. For example, a range slider state can be described in
term of the positions that the low and high thumb of the slider occupy. You can use either
Javascript literal notation, or provide a handle to the object.Example:"state": {"lowValue": 20, "highValue": 50}

Methods

ControlWrapper exposes the following additional methods:

Method

Return Type

Description

draw()

None

Draws the control. Normally the dashboard holding the control takes care of drawing it.
You should call draw() to force programmatic redraws of the control after you
change any of its other settings, like options or state.

The class name of the control. If this is a Google control, the name will not be qualified
with google.visualization. So, for example, if this were a CategoryFilter
control, it would return "CategoryFilter" rather than
"google.visualization.CategoryFilter".

getControlName()

String

Returns the control name assigned by setControlName().

getControl()

Control object reference

Returns a reference to the control created by this ControlWrapper. This will return null
until after you have called draw() on the ControlWrapper object (or on the
dashboard holding it), and it throws a ready event. The returned object only exposes one
method: resetControl(), which resets the control state to the one it was
initialized with (like resetting an HTML form element).

getContainerId()

String

The ID of the control's DOM container element.

getOption(key, opt_default_val)

Any type

Returns the specified control option value

key - The name of the option to retrieve. May be a qualified name, such as
'vAxis.title'.

opt_default_value [Optional] - If the specified value is undefined or
null, this value will be returned.

getOptions()

Object

Returns the options object for this control.

getState()

Object

Returns the control state.

setControlType(type)

None

Sets the control type. Pass in the class name of the control to instantiate. If this is a
Google control, do not qualify it with google.visualization.
So, for example, for a range slider over a numeric column, pass in
"NumberRangeFilter".

setControlName(name)

None

Sets an arbitrary name for the control. This is not shown anywhere on the control, but is for
your reference only.

setContainerId(id)

None

Sets the ID of the containing DOM element for the control.

setOption(key, value)

None

Sets a single control option value, where key is the option name and value
is the value. To unset an option, pass in null for the value. Note that key may be a
qualified name, such as 'vAxis.title'.

setOptions(options_obj)

None

Sets a complete options object for a control.

setState(state_obj)

None

Sets the control state. The state collects all the variables that the user operating the
control can affect. For example, a range slider state can be described in term of the
positions that the low and high thumb of the slider occupy.

Events

The ControlWrapper object throws the following events. Note that you must call
ControlWrapper.draw() (or draw the dashboard holding the control) before any events
will be thrown.

Name

Description

Properties

error

Fired when an error occurs when attempting to render the control.

id, message

ready

The control is ready to accept user interaction and for external method calls. If you want
to interact with the control, 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. Alternatively, you can listen for a ready event on the
dashboard holding the control and call control methods only after the event was fired.

None

statechange

Fired when the user interacts with the control, affecting its state. For example, a
statechange event will fire whenever you move the thumbs of a range slider
control. To retrieve an updated control state after the event fired, call
ControlWrapper.getState().

ChartWrapper

The following notes apply when using a ChartWrapper as part of a dashboard:

Do not set the dataTable, query, dataSourceUrl and
refreshInterval attributes explicitly. The dashboard holding the chart takes care
of feeding it the data it needs.

Do set its view attribute to declare which columns, out of all the ones present in
the dataTable given to the dashboard, are relevant for the chart, as shown in
Create Control and Chart Instances.

Controls Gallery

Filters are graphical elements that people can use to interactively select which data is
displayed on your chart. This section describes the Google Chart filters: CategoryFilter,
ChartRangeFilter, DateRangeFilter, NumberRangeFilter, and
StringFilter.

You can use any of them as a parameter to ControlWrapper.setControlType().

Note: In describing options, the dot notation is used to describe nested object
attributes. For example an option named 'ui.label' should be declared in an options
object as
var options = {"ui": {"label": "someLabelValue"} };

CategoryFilter

A picker to choose one or more between a set of defined values.

[This section requires a browser that supports JavaScript and iframes.]

State

Name

Type

Default

Description

selectedValues

Array of objects or primitive types

none

The set of values currently selected. The selected values must be a set of the overall
selectable values defined by the values option (any extraneous one will be
ignored). If the CategoryFilter does not allow multiple choice, only the first
value of the array is retained.

Options

Name

Type

Default

Description

filterColumnIndex

number

none

The column of the datatable the filter should operate upon. It is mandatory to provide either
this option or filterColumnLabel. If both present, this option takes precedence.

filterColumnLabel

string

none

The label of the column the filter should operate upon. It is mandatory to provide either
this option or filterColumnIndex. If both present,
filterColumnIndex takes precedence.

values

Array

auto

List of values to choose from. If an array of Objects is used, they should have a suitable
toString() representation for display to the user. If null or undefined, the
list of values will be automatically computed from the values present in the DataTable column
this control operates on.

useFormattedValue

boolean

false

When populating the list of selectable values automatically from the DataTable column this
filter operates on, whether to use the actual cell values or their formatted values.

ui

Object

null

An object with members to configure various aspects of the control's UI.
To specify properties of this object, you can use object literal notation, as shown here:

{label: 'Metric', labelSeparator: ':'}

ui.caption

string

'Choose a value...'

The caption to display inside the value picker widget when no item is selected.

ui.sortValues

boolean

true

Whether the values to choose from should be sorted.

ui.selectedValuesLayout

string

'aside'

How to display selected values, when multiple selection is allowed. Possible values are:

'aside': selected values will display in a single text line next to the
value picker widget,

'below': selected values will display in a single text line below the widget,

'belowWrapping': similar to below, but entries that cannot fit
in the picker will wrap to a new line,

'belowStacked': selected values will be displayed in a column below the
widget.

ui.allowNone

boolean

true

Whether the user is allowed not to choose any value. If false the user must
choose at least one value from the available ones. During control initialization, if the
option is set to false and no selectedValues state is given, the
first value from the avaiable ones is automatically seleted.

ui.allowMultiple

boolean

true

Whether multiple values can be selected, rather than just one.

ui.allowTyping

boolean

true

Whether the user is allowed to type in a text field to narrow down the list of possible
choices (via an autocompleter), or not.

ui.label

string

auto

The label to display next to the category picker. If unspecified, the label of the column the
control operates on will be used.

ui.labelSeparator

string

none

A separator string appended to the label, to visually separate the label from the category
picker.

ui.labelStacking

string

'horizontal'

Whether the label should display above (vertical stacking) or beside (horizontal stacking)
the category picker. Use either 'vertical' or 'horizontal'.

ui.cssClass

string

'google-visualization-controls-categoryfilter'

The CSS class to assign to the control, for custom styling.

ChartRangeFilter

A slider with two thumbs superimposed onto a chart, to select a range of values from the
continuous axis of
the chart.

[This section requires a browser that supports JavaScript and iframes.]

State

Name

Type

Default

Description

range.start

number, date, datetime or timeofday

Range start value

The start of the selected range, inclusive.

range.end

number, date, datetime or timeofday

Range end value

The end of the selected range, inclusive.

Options

Name

Type

Default

Description

filterColumnIndex

number

none

The index of the column in the data table the filter operates on.
It is mandatory to provide either this option or filterColumnLabel. If both are
present, this option takes precedence.

Note that it only makes sense to specify an index of a
domain column that is
embodied in the continuous axis of the chart drawn inside the control.

filterColumnLabel

string

none

The label of the column of the data table the filter operates on. It is mandatory to provide
either this option or filterColumnIndex. If both are present,
filterColumnIndex takes precedence.

Note that it only makes sense to specify an label of a
domain column that is
embodied in the continuous axis of the chart drawn inside the control.

ui

Object

null

An object with members to configure various aspects of the control's UI.
To specify properties of this object, you can use object literal notation, as shown here:

{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}

ui.chartType

string

'ComboChart'

The type of the chart drawn inside the control.
Can be one of: 'AreaChart', 'LineChart', 'ComboChart' or 'ScatterChart'.

The configuration options of the chart drawn inside the control.
Allows the same level of configuration as any chart in the dashboard,
and complies with the same format as accepted by
ChartWrapper.setOptions().

You can specify additional options or override the default ones (note that the defaults
have been carefully chosen for optimal appearance, though).

ui.chartView

Object or string (serialized Object)

null

Specification of the view to apply to the data table used to draw the chart inside the
control. Allows the same level of configuration as any chart in the dashboard,
and complies with the same format as accepted by
ChartWrapper.setView().
If not specified, the data table itself is used to draw the chart.

Please note that the horizontal axis of the drawn chart must be
continuous,
so be careful to specify ui.chartView accordingly.

ui.minRangeSize

number

Data value difference interpreted as 1 pixel

The minimum selectable range size (range.end - range.start), specified in data
value units. For a numeric axis, it is a number (not necessarily an integer).
For a date, datetime or timeofday axis, it is an integer that specifies the difference in
milliseconds.

ui.snapToData

boolean

false

If true, range thumbs are snapped to the nearest data points.
In this case, the end points of the range returned by getState() are necessarily
values in the data table.

Events

Same as documented for every ControlWrapper, only has an extra boolean property,
inProgress, that specifies whether the state is currently being changed
(either one of the thumbs or the range itself is being dragged).

inProgress

DateRangeFilter

A dual-valued slider for selecting ranges of dates.

Try moving the slider to change which rows are shown in the table below.

[This section requires a browser that supports JavaScript and iframes.]

State

Name

Type

Default

Description

lowValue

number

none

The lower extent of the selected range, inclusive.

highValue

number

none

The higher extent of the selected range, inclusive.

lowThumbAtMinimum

boolean

none

Whether the lower thumb of the slider is locked at the minimum allowed range. If set,
overrides lowValue.

highThumbAtMaximum

boolean

none

Whether the higher thumb of the slider is locked at the maximum allowed range. If set,
overrides highValue.

Options

Name

Type

Default

Description

filterColumnIndex

number

none

The column of the datatable the filter should operate upon. It is mandatory to provide either
this option or filterColumnLabel. If both present, this option takes precedence.
Must point to a column with type number.

filterColumnLabel

string

none

The label of the column the filter should operate upon. It is mandatory to provide either
this option or filterColumnIndex. If both present,
filterColumnIndex takes precedence. Must point to a column with type
number.

minValue

Date

auto

Minimum allowed value for the range lower extent. If undefined, the value will be inferred
from the contents of the DataTable managed by the control.

maxValue

Date

auto

Maximum allowed value for the range higher extent. If undefined, the value will be inferred
from the contents of the DataTable managed by the control.

ui

Object

null

An object with members to configure various aspects of the control's UI.
To specify properties of this object, you can use object literal notation, as shown here:

{label: 'Age', labelSeparator: ':'}

ui.format

Object

none

How to represent the date as a string. Accepts any valid
date format
.

ui.step

string

day

The minimum possible change when dragging the slider thumbs: can be any time unit up to "day".
("month" and "year" aren't yet supported.)

ui.ticks

number

auto

The number of ticks (fixed positions in the range bar) the slider thumbs can occupy.

ui.unitIncrement

string

'1'

The amount to increment for unit increments of the range extents. A unit increment is
equivalent to using the arrow keys to move a slider thumb.

ui.blockIncrement

number

10

The amount to increment for block increments of the range extents. A block increment is
equivalent to using the pgUp and pgDown keys to move the slider thumbs.

ui.showRangeValues

boolean

true

Whether to have labels next to the slider displaying extents of the selected range.

ui.orientation

string

'horizontal'

The slider orientation. Either 'horizontal' or 'vertical'.

ui.label

string

auto

The label to display next to the slider. If unspecified, the label of the column the control
operates on will be used.

ui.labelSeparator

string

none

A separator string appended to the label, to visually separate the label from the slider.

ui.labelStacking

string

'horizontal'

Whether the label should display above (vertical stacking) or beside (horizontal stacking)
the slider. Use either 'vertical' or 'horizontal'.

ui.cssClass

string

'google-visualization-controls-rangefilter'

The CSS class to assign to the control, for custom styling.

NumberRangeFilter

A dual-valued slider for selecting ranges of numeric values.

[This section requires a browser that supports JavaScript and iframes.]

State

Name

Type

Default

Description

lowValue

number

none

The lower extent of the selected range, inclusive.

highValue

number

none

The higher extent of the selected range, inclusive.

lowThumbAtMinimum

boolean

none

Whether the lower thumb of the slider is locked at the minimum allowed range. If set,
overrides lowValue.

highThumbAtMaximum

boolean

none

Whether the higher thumb of the slider is locked at the maximum allowed range. If set,
overrides highValue.

Options

Name

Type

Default

Description

filterColumnIndex

number

none

The column of the datatable the filter should operate upon. It is mandatory to provide either
this option or filterColumnLabel. If both present, this option takes precedence.
Must point to a column with type number.

filterColumnLabel

string

none

The label of the column the filter should operate upon. It is mandatory to provide either
this option or filterColumnIndex. If both present,
filterColumnIndex takes precedence. Must point to a column with type
number.

minValue

number

auto

Minimum allowed value for the range lower extent. If undefined, the value will be inferred
from the contents of the DataTable managed by the control.

maxValue

number

auto

Maximum allowed value for the range higher extent. If undefined, the value will be inferred
from the contents of the DataTable managed by the control.

ui

Object

null

An object with members to configure various aspects of the control's UI.
To specify properties of this object, you can use object literal notation, as shown here: