Dashboards¶

Dashboards assemble worksheets and dashboard objects into Tableau layout zones. Use this page for visible dashboard structure: sizing, titles, worksheet zones, controls, legends, text, images, web pages, buttons, and layout. Use Interactivity for action behavior.

Dashboard Object¶

{
  "name": "Executive Overview",
  "sizing": {
    "mode": "fixed",
    "width": 1200,
    "height": 800
  },
  "title": "Executive Overview",
  "worksheets": ["Sales by Category", "Profit by Segment"]
}

Field	Type	Required	Values	Description
`name`	string	Yes	Stable dashboard name	Referenced by actions, stories, and navigation.
`id`	string	No	UUID in `{...}` form	Optional stable Tableau dashboard ID. Usually omit.
`width`	integer	No	`>= 1`	Legacy fixed dashboard width. Do not combine with `sizing`. Defaults to `800` when no `sizing` is present.
`height`	integer	No	`>= 1`	Legacy fixed dashboard height. Do not combine with `sizing`. Defaults to `600` when no `sizing` is present.
`sizing`	object	No	Sizing object	Preferred dashboard sizing API.
`title`	string	No	Plain text	Dashboard title. Mutually exclusive with `title_runs`.
`title_runs`	object	No	Formatted text runs	Rich title text with field/parameter tokens. Mutually exclusive with `title`.
`title_style`	object	No	Dashboard title style	Requires either `title` or `title_runs`. See Formatting.
`subtitle_style`	object	No	Dashboard subtitle style	Requires either `title` or `title_runs`. See Formatting.
`style`	object	No	Root zone style	Styles the dashboard root zone.
`worksheets`	array	Yes	Worksheet names	Worksheets available on the dashboard.
`filter_controls`	array	No	Dashboard filter-control objects	Visible dashboard-level filter cards.
`parameter_controls`	array	No	Dashboard parameter-control objects	Visible dashboard-level parameter controls.
`color_legends`	array	No	Dashboard color-legend objects	Visible dashboard-level legends.
`text_boxes`	array	No	Text box objects, max 8	Text zones addressable from `layout` by zero-based index.
`images`	array	No	Image objects, max 8	Image zones addressable from `layout` by zero-based index.
`web_pages`	array	No	Web page objects, max 8	Web page zones addressable from `layout` by zero-based index.
`navigation_buttons`	array	No	Navigation button objects, max 16	Dashboard navigation buttons addressable from `layout`.
`download_buttons`	array	No	Download button objects, max 16	Dashboard export buttons addressable from `layout`.
`layout`	object	No	Tiled or floating layout root	Explicitly places dashboard objects. If omitted, the compiler emits the legacy deterministic stack/control rail.
`device_layouts`	object	No	`tablet`, `phone`	Device-specific layout metadata.

Sizing Object¶

Field	Type	Required	Values	Description
`mode`	string	Yes	`automatic`, `fixed`, `range`, `vscroll`	Dashboard size behavior.
`width`	integer	With `fixed`	`>= 1`	Fixed width. Not allowed with `automatic`, `vscroll`, or `range`.
`height`	integer	With `fixed` and `vscroll`	`>= 1`	Fixed height for `fixed`, scroll height for `vscroll`.
`min_width`	integer	With `range`	`>= 1`	Minimum responsive width.
`min_height`	integer	With `range`	`>= 1`	Minimum responsive height.
`max_width`	integer	With `range`	`>= 1`	Maximum responsive width.
`max_height`	integer	With `range`	`>= 1`	Maximum responsive height.

{
  "sizing": {
    "mode": "range",
    "min_width": 900,
    "min_height": 600,
    "max_width": 1400,
    "max_height": 1000
  }
}

Dashboard Controls¶

Filter Control Object¶

Field	Type	Required	Values	Description
`worksheet`	string	Yes	Worksheet on the same dashboard	Source worksheet that owns the filter.
`field`	string	Yes	Field ref	Filtered field.
`date_part`	string	No	`month`, `quarter`, `year`	Targets date-part filter controls.
`mode`	string	No	`checkdropdown`, `dropdown`, `radiolist`, `slider`	Display mode.
`values`	string	No	`context`, `relevant`	Member list behavior.
`title`	string	No	Display text	Title override.
`show_all`	boolean	No	`true`, `false`	Show or hide the All option.
`show_exclude`	boolean	No	`true`, `false`	Show or hide the Exclude option.
`show_filter_state`	boolean	No	`true`, `false`	Show or hide filter-state text.
`show_search`	boolean	No	`true`, `false`	Show or hide search UI.
`show_apply`	boolean	No	`true`, `false`	Show or hide Apply button.
`show_title`	boolean	No	`true`, `false`	Show or hide the control title.
`fixed_size`	integer	No	`>= 1`	Fixed zone size.
`style`	object	No	Filter-control style	Allowlisted dashboard zone style. See Formatting.

Parameter Control Object¶

Field	Type	Required	Values	Description
`parameter`	string	Yes	Workbook parameter name	Parameter to expose.
`mode`	string	No	`compact`, `slider`, `type_in`	Display mode. Defaults to `compact`.
`title`	string	No	Plain text	Title override. Mutually exclusive with `title_runs`.
`title_runs`	object	No	Formatted text runs	Rich title. Mutually exclusive with `title`.
`show_title`	boolean	No	`true`, `false`	When `false`, `title` and `title_runs` are not allowed.
`fixed_size`	integer	No	`>= 1`	Fixed zone size.
`style`	object	No	Parameter-control style	Allowlisted dashboard zone style.

Color Legend Object¶

Field	Type	Required	Values	Description
`worksheet`	string	Yes	Worksheet on dashboard	Worksheet that owns the Color encoding.
`field`	string	Yes	Field ref or supported pseudo-field	Must match the worksheet's Color encoding.
`show_title`	boolean	No	`true`, `false`	Show or hide legend title.
`layout`	string	No	`grid`, `horizontal`	Legend item layout.
`fixed_size`	integer	No	`>= 1`	Fixed zone size.
`style`	object	No	Color-legend style	Allowlisted dashboard zone style.

{
  "filter_controls": [
    {
      "worksheet": "Sales by Category",
      "field": "[Orders].[Category]",
      "mode": "checkdropdown",
      "values": "relevant",
      "title": "Product category",
      "show_search": true,
      "show_apply": true
    }
  ],
  "parameter_controls": [
    {
      "parameter": "Sales Target",
      "mode": "type_in",
      "title_runs": {
        "runs": [
          {
            "text": "Target",
            "bold": true
          }
        ]
      }
    }
  ],
  "color_legends": [
    {
      "worksheet": "Sales by Category",
      "field": "[Orders].[Segment]",
      "layout": "grid",
      "show_title": false
    }
  ]
}

Dashboard Objects¶

Text Box Object¶

Field	Type	Required	Values	Description
`text`	string	One of `text` or `text_runs`	Plain text	Literal dashboard text.
`text_runs`	object	One of `text` or `text_runs`	Formatted text object	Rich text runs.
`style`	object	No	Text box style	Allowlisted dashboard zone style.

Image Object¶

Field	Type	Required	Values	Description
`asset`	string	Yes	Package member path	Must point at a packaged image asset.
`alt_text`	string	No	Display/accessibility text	Tableau image alt text.
`fit`	boolean	No	`true`, `false`	Fit image to zone. Defaults to `true`.
`style`	object	No	Image style	Allowlisted dashboard zone style.

Web Page Object¶

Field	Type	Required	Values	Description
`url`	string	Yes	`http://...` or `https://...` URI	Dashboard web page object URL.

Field	Type	Required	Values	Description
`text`	string	Yes	Button label	Visible text.
`target_sheet`	string	Yes	Worksheet or dashboard name	Sheet opened by the button.
`tooltip`	string	No	Tooltip text	Hover tooltip.
`style`	object	No	Navigation-button style	Font, border, and background style allowlist.

Download Button Object¶

Field	Type	Required	Values	Description
`format`	string	No	`pdf`	Export format. Defaults to `pdf`.
`style`	object	No	Navigation-button style	Uses the same style object as navigation buttons.

{
  "text_boxes": [
    {
      "text_runs": {
        "runs": [
          {
            "text": "Executive Summary",
            "font_size": 14,
            "bold": true
          }
        ]
      }
    }
  ],
  "images": [
    {
      "asset": "Images/logo.png",
      "alt_text": "Company logo",
      "fit": true
    }
  ],
  "web_pages": [
    {
      "url": "https://example.com/status"
    }
  ],
  "navigation_buttons": [
    {
      "text": "Open detail",
      "target_sheet": "Detail Dashboard",
      "tooltip": "Navigate to detail"
    }
  ],
  "download_buttons": [
    {
      "format": "pdf"
    }
  ]
}

Layout Root¶

layout may be a tiled layout node or a floating root. A layout should place every dashboard object exactly once: all worksheets, controls, legends, text boxes, images, web pages, navigation buttons, download buttons, and blank spacers.

Tiled Layout Nodes¶

`kind`	Required Fields	Optional Fields	Description
`container`	`direction`, `children`	`style`, `container_style`	Horizontal or vertical group. `direction` is `horizontal` or `vertical`.
`worksheet`	`worksheet`	`show_title`, `style`	Worksheet zone. `show_title` defaults to `true`.
`blank`	none	`style`	Blank spacer zone.
`text_box`	`index`	none	Places `text_boxes[index]`.
`image`	`index`	none	Places `images[index]`.
`web_page`	`index`	none	Places `web_pages[index]`.
`navigation_button`	`index`	none	Places `navigation_buttons[index]`.
`download_button`	`index`	none	Places `download_buttons[index]`.
`filter_control`	`worksheet`, `field`	`date_part`	Places a filter control.
`parameter_control`	`parameter`	none	Places a parameter control.
`color_legend`	`worksheet`, `field`	none	Places a color legend.

{
  "layout": {
    "kind": "container",
    "direction": "horizontal",
    "children": [
      {
        "kind": "worksheet",
        "worksheet": "Sales by Category",
        "show_title": false
      },
      {
        "kind": "container",
        "direction": "vertical",
        "children": [
          {
            "kind": "filter_control",
            "worksheet": "Sales by Category",
            "field": "[Orders].[Category]"
          },
          {
            "kind": "text_box",
            "index": 0
          },
          {
            "kind": "blank"
          }
        ]
      }
    ]
  }
}

Floating Layout¶

Floating roots use normalized coordinates from 0 to 100000. Each child must fit inside the normalized content area: x + width <= 100000 and y + height <= 100000.

Field	Type	Required	Values	Description
`kind`	string	Yes	`floating`	Root layout kind.
`children`	array	Yes	Floating child nodes	Direct floating leaves only; nested containers are not supported.
`x`	integer	Child only	`0` to `100000`	Normalized left position.
`y`	integer	Child only	`0` to `100000`	Normalized top position.
`width`	integer	Child only	`1` to `100000`	Normalized width.
`height`	integer	Child only	`1` to `100000`	Normalized height.

{
  "layout": {
    "kind": "floating",
    "children": [
      {
        "kind": "worksheet",
        "worksheet": "Sales by Category",
        "show_title": false,
        "x": 0,
        "y": 0,
        "width": 68000,
        "height": 66000
      },
      {
        "kind": "text_box",
        "index": 0,
        "x": 70000,
        "y": 0,
        "width": 30000,
        "height": 18000
      }
    ]
  }
}

Device Layouts¶

Field	Type	Required	Values	Description
`device_layouts.tablet.sizing`	object	Yes for tablet layout	`mode: "automatic"`	Tablet sizing.
`device_layouts.tablet.title`	string	No	Display text	Tablet layout title.
`device_layouts.phone.sizing`	object	Yes for phone layout	`mode: "vscroll"`	Phone sizing.
`device_layouts.phone.layout`	string	Required when `worksheets` or `style` is set	`single_column`	Phone layout mode.
`device_layouts.phone.title`	string	No	Display text	Phone layout title.
`device_layouts.phone.style`	object	No	Root zone style	Requires `layout: "single_column"`.
`device_layouts.phone.worksheets`	array	No	Worksheet names	Phone-specific worksheet order; requires `layout: "single_column"`.

{
  "device_layouts": {
    "tablet": {
      "sizing": {
        "mode": "automatic"
      },
      "title": "Tablet Overview"
    },
    "phone": {
      "sizing": {
        "mode": "vscroll",
        "height": 1400
      },
      "layout": "single_column",
      "worksheets": ["Sales by Category", "Profit by Segment"]
    }
  }
}