Dashboards can be created in one of two ways. User-defined dashboards are created using the Looker UI, and are described on theCreating user-defined dashboards documentation page. Dashboards can also becreated using LookML and their overall settings modified as discussed on this page.

This page describes the LookML dashboard parameters that affect the entire dashboard.

A LookML dashboard also containselements, which are the data visualizations, text tiles, and buttons on the dashboard. See theDashboard element parameters page for links to the reference pages for each individual element type.

Example usage

- dashboard: dashboard_name  preferred_viewer: dashboards | dashboards-next  title: "chosen dashboard title"  description: "chosen dashboard description"  enable_viz_full_screen: true | false  extends: name_of_dashboard_being_extended  extension: required  layout: tile | static | grid | newspaper  rows:    - elements: [element_name, element_name, ...]      height: N  tile_size: N  width: N  refresh: N (seconds | minutes | hours | days)  auto_run: true | false  # DASHBOARD FILTER PARAMETERS  crossfilter_enabled: true | false  filters_bar_collapsed: true | false  filters_location_top: true | false  filters:  - name: filter_name    title: "chosen filter title"    type: field_filter | number_filter | date_filter | string_filter    model: model_name    explore: explore_name    field: view_name.field_name    default_value: Looker filter expression    allow_multiple_values: true | false    required: true | false    ui_config:      type: button_group | checkboxes | range_slider | tag_list | radio_buttons |            button_toggles | dropdown_menu | slider | day_picker | day_range_picker |            relative_timeframes | advanced      display: inline | popover | overflow      options:        min: N        max: N      - value options    listens_to_filters:    - filter_name      field: view_name.field_name  # EMBEDDED DASHBOARD PARAMETERS  embed_style:    background_color: "css_color"    show_title: true | false    title_color: "css_color"    show_filters_bar: true | false    tile_background_color: "css_color"    tile_text_color: "css_color"  # ELEMENTS PARAMETERS  elements:  # One or more element declarations

Parameter definitions

dashboard

Thedashboard parameter declares a new dashboard and specifies a name for the dashboard. The maximum number of characters is 255; and allowed characters are letters (A-Z), numbers (0-9), dashes (-), and underscores (_). It is typically best practice to place each LookML dashboard in its own LookML file, but it is possible to declare multiple dashboards in a single file.

- dashboard: sales_overview

To display anything, a dashboard requires at least one element to be added using theelements parameter.

preferred_viewer

Before legacy dashboard deprecation in Looker 23.6, thepreferred_viewer parameter let you choose the format for viewing and downloading a dashboard as either Looker's defaultdashboard experience or as a legacy dashboard.

title(for dashboard)

This section refers to thetitle parameter that is part of adashboard.

title can also be used as part of a dashboard filter, described on thetitle (for filters) section on this page.

title can also be used as part of any dashboard element. A representative example of its usage is provided on thecolumn chart elements documentation page.

Thetitle parameter lets you change how a dashboard name will appear to users infolders and at the top of the dashboard. If not specified, the title defaults to the name of the dashboard. The title text can belocalized.

Consider this example:

- dashboard: sales_overview  title: "1) Sales Overview"

If you did this, instead of the dashboard appearing asSales Overview, it would appear as1) Sales Overview.

description(for dashboard)

This section refers to thedescription parameter that is part of adashboard.

description can also be used as part of an Explore, as described on thedescription (for Explores) parameter documentation page.

description can also be used as part of a field, as described on thedescription (for fields) parameter documentation page.

Thedescription parameter lets you add a description to a LookML dashboard.

The contents of thedescription parameter will appear in theDescription field of theDashboard Details panel of a LookML dashboard.

The description is displayed under the dashboard title in thelists of dashboards when viewed in a folder set tolist view. If a description is not specified, the list displays only the dashboard title.

The description text can belocalized.

enable_viz_full_screen

This parameter only takes effect when theFull Screen Visualizations setting is enabled by a Looker admin. TheFull Screen Visualization setting is enabled by default.

Theenable_viz_full_screen parameter lets you set whether dashboard viewers can see dashboard tiles infull-screen and expanded views. It is equivalent to theAllow full-screen mode for visualizations dashboard setting.

This parameter accepts the valuestrue (full-screen and expanded views available) andfalse (full-screen and expanded views not available). The default value istrue.

extends

As described on theReusing codes with extends documentation page, theextends parameter lets you base one LookML dashboard on another LookML dashboard, possibly adding or overriding some settings. Theextends parameter accepts the name of another LookML dashboard.

When extending an object, be aware that localization rules apply to your extensions as well. If you are extending an object and then defining new labels or descriptions, you should provide localization definitions in your project's locale strings files. See theLocalizing your LookML model documentation page for more information.

extension

As described on theReusing code with extends documentation page, theextension parameter indicates that the dashboardmust be extended by another dashboard. This dashboard is never visible to other users but can be used as a template to create other dashboards that are visible to other users. Theextension parameter only accepts the valuerequired. If theextension parameter is not included, extension is not required for the dashboard.

layout

Thelayout parameter sets the layout method that Looker will use when positioning dashboard elements. It accepts the following values:

• newspaper: Dashboard elements will appear in a 24-column grid. The default size for an element is a width of 8 columns and a height of 6 rows. Elements are configurable along this grid, specified by thewidth,height,row, andcolelement parameters. This layout option is used whena user-defined dashboard is converted to a LookML dashboard, as well as being the default layout when a new LookML dashboard is created through the Looker IDE. In addition,newspaper andgrid are the only layouts that supportconversion from a LookML dashboard to a user-defined dashboard.

• grid: Dashboard elements will appear with dynamic widths, which are based on a set of rows that you define with therows parameter and its subparameterselements andheight.newspaper andgrid are the only layouts that supportconversion from a LookML dashboard to a user-defined dashboard.

• static: Dashboard elements will appear in the order in which they are listed in the LookML file. Each dashboard element must be positioned manually by using thetop andleft parameters. These parameters apply to all element types, and details about their usage appear on thedocumentation pages for each individual visualization type. For representative examples of howtop andleft work, see theColumn chart parameters for LookML dashboards documentation page.static does not supportconversion from a LookML dashboard to a user-defined dashboard.

• tile: Dashboard elements will appear in the order in which they are listed in the LookML file. The width of the dashboard is dynamic, and is based on the width of the browser. The dashboard elements will dynamically position themselves within the browser to fill the available space.tile does not supportconversion from a LookML dashboard to a user-defined dashboard.

rows

Forlayout: grid dashboards, therows parameter starts the section of LookML where you define which elements should go into which rows, as well as the height of each row. Within each row, each element has the same width. If you don't list an element in this section it won't appear on the dashboard.

- dashboard: sales_overview  layout: grid  rows:    - elements: [element_name, element_name, ...]      height: 200    - elements: [element_name, element_name, ...]      height: 300

elements

Theelements parameter takes a list of dashboard element names, separated by commas. Eachelements declaration creates a new row in the dashboard. The elements that are placed into a row will all have the same width. So, if you place 2 elements in a row, they will each take 50% of the available space. If you place 4 elements into a row, they will each take 25% of the available space.

height

Theheight parameter defines the height of a row in pixels. The default value is 300.

tile_size

Forlayout: tile andlayout: static dashboards, the unit that is used to size and position elements is tile size. You definetile_size in pixels, and the default value is 160. For example:

- dashboard: sales_overview  layout: tile  tile_size: 100

In this situation, a dashboard element withheight: 5 andwidth: 3 will be 500 pixels high, and 300 pixels wide. Theheight andwidth parameters apply to all element types, and details about their usage appear on thedocumentation pages for each individual visualization type. For a representative example of howheight andwidth work, see theColumn chart parameters for LookML dashboards documentation page.

width

This section refers to thewidth parameter that is part of adashboard.

width can also be used as part of a dashboard element. A representative example its usage is provided on the documentation page forcolumn chart elements.

Forlayout: static dashboards, thewidth parameter defines the total dashboard width that you plan to use in pixels. Thewidth parameter willnot restrict the dashboard to a certain size if you define too large of an element, or too many elements in a row. Rather, thewidth setting helps to keep the dashboard centered on the screen. If you don't set a width, the default is 1200.

- dashboard: sales_overview  layout: static  width: 800

refresh

This section refers to therefresh parameter that is part of adashboard.

refresh can also be used as part of a dashboard element. A representative example of its usage is provided on the documentation page forcolumn chart elements.

Therefresh parameter allows a dashboard to automatically reload on some periodic basis, thereby retrieving fresh data. This is often helpful in settings where a dashboard is constantly displayed, such as on an office TV. Note that the dashboard must be open in a browser window for this parameter to have an effect. This setting does not run in the background to "pre-warm" the dashboard cache.

The refresh rate can be any number (without decimals) of seconds, minutes, hours or days. For example:

- dashboard: sales_overview  refresh: 2 hours

Use caution when setting short refresh intervals. Since dashboards can contain many queries, some of which may be resource intensive, certain dashboards may strain your database.

auto_run

Theauto_run parameter determines whether a dashboard will run when it is initially opened or reloaded. The default value istrue. When this parameter is set tofalse, users will need to press aRun button to load the dashboard. For example, a dashboard like this will automatically run when opened:

- dashboard: sales_overview  auto_run: true

Regardless of theauto_run setting, users must always click aRun button after changing filter values. This helps to prevent unwanted reloads when a user pauses during a filter change or wants to change multiple filters at the same time.

crossfilter_enabled

Thecrossfilter_enabled parameter lets youturn cross-filters on or off for a dashboard. When this parameter is set totrue, dashboard viewers cancreate cross-filters on the dashboard by clicking certain data points.

- dashboard: sales_data  crossfilter_enabled: true

filters_bar_collapsed

Thefilters_bar_collapsed parameter lets you set the dashboard filter bar as defaultcollapsed or expanded for a dashboard. When this parameter is set totrue, the filter bar is default collapsed. Dashboard viewers can expand the filter bar by clicking thefilters icon. The default for this setting isfalse.

- dashboard: sales_data  filters_bar_collapsed: true

filters_location_top

Thefilters_location_top parameter lets you place the dashboard filter bar at thetop or the right for a dashboard. When this parameter is set totrue, the filter bar appears at the top of the dashboard; when it is set tofalse, the filter bar appears at the right of the dashboard. The default for this setting istrue.

- dashboard: sales_data  filters_location_top: false

filters

This section refers to thefilters parameter that is part of adashboard.

filters can also be used as part of a dashboard element. A representative example of its usage is provided on the documentation page forcolumn chart elements.

filters can also be used as part of a measure, described on thefilters parameter documentation page.

Thefilters parameter starts the section of LookML where you define dashboard filters. Filters appear at the top of the dashboard and let users change the data behind dashboard elements.

For a filter to impact an element, the element must be set up to "listen" for that filter, using thelisten parameter. This parameter applies to all element types excepttype: text andtype: button. For a representative example of howlisten works, see theColumn chart parameters for LookML dashboards documentation page.

When filters are applied to an element in this manner, it's important for the filter type to match the dimension or measure type that is listening for the filter (seeBuilding LookML dashboards for more details). Filters have the following form:

filters:- name: filter_name  title: "chosen filter title"  type: field_filter | number_filter | date_filter | string_filter  model: model_name  explore: explore_name  field: view_name.field_name  default_value: Looker filter expression  allow_multiple_values: true | false  required: true | false  listens_to_filters:  - filter_name    field: view_name.field_name

name

This section refers to thename parameter that is part of adashboard filter.

name can also be used as part of a dashboard element. A representative example of its usage is provided on the documentation page forcolumn chart elements.

Eachname declaration creates a new dashboard filter, and assigns a name to it. The name will be referenced in thelisten parameter of elements that should be impacted by the filter. Thelisten parameter applies to all element types besidestype: text, and details about its usage appear on thedocumentation pages for each individual visualization type. For a representative example of howlisten works, see theColumn chart parameters for LookML dashboards documentation page.

filters:- name: order_date

title(for filters)

This section refers to thetitle parameter that is part of adashboard filter.

title can also be used as part of a dashboard, as described in thetitle (for dashboard) section on this page.

title can also be used as part of a dashboard element. A representative example of its usage is provided on theColumn chart parameters for LookML dashboards documentation page.

Thetitle parameter lets you change how a filter name will appear to users at the top of a dashboard. If not specified, the title defaults to the name of the filter.

Consider this example:

filters:- name: order_date  title: "Order Date(s)"

If you did this, instead of the filter appearing asOrder Date, it would appear asOrder Date(s).

type

This section refers to thetype parameter that is part of adashboard filter.

type can also be used as part of a dashboard element, described on thetype (for LookML dashboards) parameter documentation page.

type can also be used as part of a join, described on thetype parameter parameter documentation page.

type can also be used as part of a dimension, described on theDimension, filter, and parameter types documentation page.

type can also be used as part of a measure, described on theMeasure types documentation page.

Thetype parameter specifies the type of input that will be placed in the filter. While any type of input (such as a date) could be written into thetype: string_filter filter, being more specific provides a more tailored filter widget to the user. The 4 types of filter are:

• field_filter: Should generally be your default choice, when you can specify an underlying dimension or measure. Usingtype: field_filter and associating the filter with atype:string field causes the filter to suggest possible filter values.
• number_filter: Lets the user input a number/integer value or expression.
• date_filter: Lets the user input a date value or expression.
• string_filter: Lets the user input freeform text.

field_filter

Suggests options to choose from, changes its presentation to users based on the underlying field you specify.

This should be your go-to filter type in situations where you want to make suggestions to users as they interact with the filter. The dimension from which suggestions will be pulled is defined by using theexplore andfield parameters, and must be a field oftype: string to generate filter suggestions.

Suggestions may not work if the field comes from a derived table, ifsql_always_where is used on the Explore, or if the field is a measure.

filters:- name: order_date  type: field_filter  explore: orders  field: orders.order_date  # must be of the form view_name.dimension_name

number_filter

Does not make suggestions, lets the user enter an integer/number value or expression.

filters:- name: order_value  type: number_filter

date_filter

Does not make suggestions, lets the user enter a date value or expression.

filters:- name: order_date  type: date_filter

string_filter

Does not make suggestions, lets the user enter freeform text.

filters:- name: customer_name  type: string_filter

default_value

Thedefault_value parameter lets you specify a default value to use for a filter. This value can be helpful to users by suggesting a reasonable starting point.

Make sure to match the default value with the type of filter being used. For example:

filters:- name: order_value  type: number_filter  default_value: "50 to 100"- name: order_date  type: date_filter  default_value: "last 30 days"- name: customer_name  type: string_filter  default_value: "John Doe"

You can use filter expressions to create default values. TheLooker filter expressions documentation page describes this in more detail.

When you use both thedefault_value and theui_config parameters, filter expressions must be compatible with the value given to thetype subparameter ofui_config and the data types that support thetype value.

You can also use the_localization and_user_attributes Liquid variables for flexible default filter values.

allow_multiple_values

Theallow_multiple_values parameter lets you control whether users can select a single filter value or multiple filter values. When this parameter is set totrue (the default), users can select multiple values for the filter. When this parameter is set tofalse, users are able to select only a single filter value.

For example:

filters:- name: Order ID  title: Order ID  type: field_filter  allow_multiple_values: true  required: false  model: thelookstore  explore: orders  field: orders.id

required

Therequired parameter lets you require that users provide a value for the filter in order to run the dashboard. By default, filters don't require values. If a filter that does not require a value and is left blank, the data simply isn't restricted by the filter field. If a filter that does require a value and is left blank, the dashboard won't run.

filters:  - name: State    title: State    type: field_filter    required: true

ui_config

Theui_config subparameter offilters lets you configure filter settings for a LookML dashboard. These settings include thetypes of filter controls used, theplacement of filter controls, andpossible filter values.

For example:

  filters:  - name: City    title: City    type: field_filter    default_value: San Francisco    allow_multiple_values: true    required: false    ui_config:      type: button_group      display: inline      options:      - San Francisco      - New York      - Tokyo    model: thelook    explore: order_items    field: users.city

See theAdding and editing user-defined dashboard filters documentation page for more information about configuring filters with the UI.

type

Thetype subparameter ofui_config lets you specify thetypes of filter controls that are shown.

Depending on the value you enter fortype, filter controls can be single selection or multiple selection.

The values thattype supports depend on the LookML datatype that is assigned to the field that you're filtering on.

display

You can can use thedisplay subparameter ofui_config to set the position of a dashboard filter. You can position a filter by assigning one of the following values todisplay:

• inline: The filter is displayed directly in the top bar of the dashboard.
• popover: A summary value appears in the top bar of the dashboard; click the value to see the full filter.
• overflow: AMore button appears in the top bar of the dashboard with a numeric indicator of how many overflow filters there are; users can click the button to see the overflow filters and their values.

Some filtertypes can only be displayed in certain ways. For example, filters oftype: day_picker can only be displayed asinline oroverflow. If you give a filter adisplay value that is not valid for thattype, the filter will display as eitherinline orpopover, whichever is valid. To learn more, see theAdding and editing user-defined dashboard filters documentation page.

For information about positioning dashboard filters using the UI, see theAdding and editing user-defined filters documentation page.

options

The optionaloptions subparameter ofui_config lets you specify thevalues that a user can choose from totemporarily update dashboard filter values when users view a LookML dashboard. If you don't specify any values foroptions, Looker pulls the first values from the database.

For example, you can setSan Francisco,New York, andTokyo as the possible values for a filter on theusers.city field as follows:

ui_config:  type: button_group  display: inline  options:  - San Francisco  - New York  - Tokyo

If thetype subparameter ofui_config is set torange_slider orslider, you can use themin andmax subparameters ofoptions:

• min: Set the minimum possible value for a filter.
• max: Set the maximum possible value for a filter.

For example:

ui_config:  type: range_slider  display: inline  options:    min: 0    max: 500

model

For dashboard filters oftype: field_filter, you need to define a model from which the filter will pull suggestions. Themodel parameter specifies which model contains the field you want to use.

filters:- name: State  title: State  type: field_filter  default_value: California  model: thelookstore  explore: users  field: users.state

explore

This section refers to theexplore parameter that is part of adashboard filter.

explore can also be used as part of a model, described on theexplore parameter documentation page.

explore can also be used as part of a dashboard element. A representative example of its usage is provided on the documentation page forcolumn chart elements.

For dashboard filters oftype: field_filter, you need to define a field from which the filter will pull suggestions. Theexplore parameter specifies which Explore contains the field you want to use.

filters:- name: order_date  type: field_filter  explore: orders  field: orders.order_date

field

For dashboard filters oftype: field_filter, you need to define a field from which the filter will pull suggestions. Thefield parameter specifies which field you want to use. It is important to use the fully scoped field name. In other words, useview_name.field_name, not justfield_name.

filters:- name: order_date  type: field_filter  explore: orders  field: orders.order_date

listens_to_filters

For dashboard filters oftype: field_filter, you can narrow suggestions for the filter based on what the user enters for another filter oftype: field_filter.

In the following example, the suggestions provided for theState filter will be based on the values from theOrder ID filter. Whatever values are selected for theOrder ID filter will have associatedusers.state values, and those values will be suggested values for theState filter. See theAdding and editing user-defined dashboard filters documentation page for more information.

filters:- name: State  title: State  type: field_filter  model: thelookstore  explore: users  listens_to_filters:  - Order ID  field: users.state

embed_style

Theembed_style parameter starts the section of LookML where you customize the appearance of anembedded dashboard.embed_style and its associated parameters are supported only on embedded dashboards and are ignored if the dashboard is not embedded.

After you make changes toembed_style, you mustdeploy your LookML to production in order to see yourembed_style settings reflected in the embedded LookML dashboard.

For the following embedded dashboard attributes that specify a color, the color value can be a hex string like#2ca6cd or aCSS named color string likemediumblue.

Embedded dashboard customizations have the following form:

embed_style:  background_color: "css_color"  show_title: true | false  title_color: "css_color"  show_filters_bar: true | false  tile_background_color: "css_color"  tile_text_color: "css_color"

background_color

Sets the color of the background of an embedded dashboard.

embed_style:  background_color: "#ffffff"

show_title

Specifies whether the embedded dashboard title is visible to users.

embed_style:  show_title: false

title_color

Sets the color of the title of an embedded dashboard.

embed_style:  title_color: "#008000"

show_filters_bar

Specifies whether the embedded dashboard filters are visible to users.

This parameter affects only the cosmetic appearance of the dashboard, not a user's ability to access data. Hiding the filters bar does NOT prevent users from changing filters by other means. For information on how to set up secure data access control policies, see theAccess control and permission management documentation page.

embed_style:  show_filters_bar: true

tile_background_color

Sets the color of the background of all tiles on an embedded dashboard.

embed_style:  tile_background_color: "lightyellow"

tile_text_color

Sets the color of text on all tiles on an embedded dashboard.

embed_style:  tile_text_color: "crimson"

elements

This section refers to theelements parameter that is part of adashboard.

elements can also be used as part of a dashboard row, described on theelements for rows section on this page.

Theelements parameter starts the section of LookML where you define the elements that will make up a dashboard. There are many parameters that can define the appearance of a dashboard element. They are described in more detail on theDashboard element parameters page.

- dashboard: sales_overview  layout: tile  elements:  - name: order_count    type: single_value    model: ecommerce    explore: orders    measures: [orders.count]

Think about the number and complexity of elements that you add to a LookML dashboard. More elements require more browser resources, which increases dashboard rendering time. Similarly, elements that render large amounts of data may impact dashboard performance. If rendering becomes an issue, consider reducing the complexity of dashboard element queries or creating multiple dashboards with fewer elements.