Skip to content

Interactivity

Interactivity covers filters, visible controls, highlighters, and dashboard actions. Worksheet and datasource filters constrain data. Dashboard and worksheet controls expose those filters or parameters. Actions connect user events to filter, highlight, parameter, URL, or navigation behavior.

Filter Objects

The same filter object family is used in worksheets[].filters. Datasource filters use a narrower subset documented on Datasources.

Filter kind Required Fields Optional Fields Description
categorical field, kind, one of members or exclude context Include listed members or exclude one member/null.
quantitative field, kind, at least one of min or max context, include_nulls Numeric range filter.
date_range field, kind, at least one of min or max context, include_nulls ISO date range filter.
relative_date field, kind, period, first_period, last_period anchor, context, include_future, include_nulls Relative date window.
date_part field, kind, date_part, either members or min/max context Discrete date-part member or range filter.
top_n field, kind, limit, direction, by context Top or bottom N dimension members by an aggregate.
condition field, kind, by, operator, value context Aggregate condition filter.
wildcard field, kind, mode, match context String wildcard filter.

Shared Filter Fields

Field Type Required Values Description
field string Yes Field ref Field being filtered.
kind string Yes See filter kinds Discriminates the filter shape.
context boolean No true, false Emits a Tableau context filter when supported.
include_nulls boolean Quantitative/date filters only true, false Includes null values in the filter result.

Categorical Filter

Field Type Required Values Description
members array One of members or exclude strings, numbers, booleans Included member list.
exclude object One of members or exclude Object with members array Member/null exclusion rule. 
{
  "field": "[Orders].[Category]",
  "kind": "categorical",
  "members": ["Furniture", "Technology"],
  "context": true
}

{
  "field": "[Orders].[Category]",
  "kind": "categorical",
  "exclude": {
    "members": [null]
  }
}

Range And Date Filters

Field Type Required Values Description
min number, string date, or boolean range value At least one of min/max Numeric value for quantitative, ISO date for date_range Lower bound.
max number, string date, or boolean range value At least one of min/max Numeric value for quantitative, ISO date for date_range Upper bound. 
[
  {
    "field": "[Orders].[Sales]",
    "kind": "quantitative",
    "min": 100,
    "max": 500,
    "include_nulls": true
  },
  {
    "field": "[Orders].[Order Date]",
    "kind": "date_range",
    "min": "2026-01-01",
    "max": "2026-12-31"
  }
]

Relative Date Filter

Field Type Required Values Description
period string Yes day, week, month, quarter, year Date grain.
first_period integer Yes Any integer Window start relative to anchor/current period.
last_period integer Yes Any integer Window end relative to anchor/current period.
anchor string No ISO date Fixed anchor date. When present, include_future must be true.
include_future boolean No true, false Includes future periods. Required as true with anchor. 
{
  "field": "[Orders].[Order Date]",
  "kind": "relative_date",
  "period": "month",
  "first_period": -5,
  "last_period": 0,
  "include_nulls": false
}

Date Part, Top N, Condition, And Wildcard

Field Type Required Values Description
date_part string Date-part filters month, quarter, year Discrete date part.
limit integer Top N >= 1 Number of members.
direction string Top N top, bottom Ranking direction.
by object Top N and condition Aggregate shelf item Aggregate used to rank or compare.
operator string Condition =, !=, >, >=, <, <= Comparison operator.
value number Condition Any number Comparison value.
mode string Wildcard contains, starts_with, ends_with, exact Match behavior.
match string Wildcard Non-empty string Text pattern. 
[
  {
    "field": "[Orders].[Order Date]",
    "kind": "date_part",
    "date_part": "month",
    "members": [1, 2, 3]
  },
  {
    "field": "[Orders].[Sub-Category]",
    "kind": "top_n",
    "limit": 10,
    "direction": "top",
    "by": {
      "field": "[Orders].[Sales]",
      "aggregation": "sum"
    }
  },
  {
    "field": "[Orders].[Category]",
    "kind": "wildcard",
    "mode": "contains",
    "match": "Office"
  }
]

Visible Controls

Worksheet cards live on worksheets; dashboard controls live on dashboards. Both reference existing parameters or filters.

Surface Field Values Notes
Worksheet filter card worksheets[].filter_cards[] field, optional date_part, mode, title Modes: checkdropdown, dropdown, radiolist, slider.
Worksheet parameter card worksheets[].parameter_cards[] parameter, optional mode, title, style Modes: compact, slider, type_in.
Dashboard filter control dashboards[].filter_controls[] worksheet, field, display options, optional style Defines dashboard-level quick filter zone.
Dashboard parameter control dashboards[].parameter_controls[] parameter, mode/title/show options, optional style Defines dashboard-level parameter control zone.
Worksheet highlighter worksheets[].highlighters[] Field refs or aggregate objects Adds worksheet highlighter cards. 
{
  "worksheets": [
    {
      "name": "Filtered Sales",
      "datasource": "Orders",
      "rows": ["[Orders].[Category]"],
      "cols": [
        {
          "field": "[Orders].[Sales]",
          "aggregation": "sum"
        }
      ],
      "filters": [
        {
          "field": "[Orders].[Category]",
          "kind": "categorical",
          "members": ["Furniture", "Technology"]
        }
      ],
      "filter_cards": [
        {
          "field": "[Orders].[Category]",
          "mode": "dropdown",
          "title": "Choose category"
        }
      ],
      "highlighters": ["[Orders].[Segment]"],
      "mark": "bar"
    }
  ],
  "dashboards": [
    {
      "name": "Sales Dashboard",
      "worksheets": ["Filtered Sales"],
      "filter_controls": [
        {
          "worksheet": "Filtered Sales",
          "field": "[Orders].[Category]",
          "mode": "checkdropdown",
          "values": "relevant",
          "show_search": true,
          "show_apply": true
        }
      ]
    }
  ]
}

Dashboard Action Object

Top-level actions[] objects attach behavior to dashboard events.

Field Type Required Values Description
name string Yes Stable action name Tableau action name.
kind string Yes filter, highlight, parameter, url, go_to_sheet Action type.
activation string No hover, select User trigger.
source object Yes Action source object Dashboard source, usually with a worksheet.
target object Filter/highlight only Action target object Target dashboard and optional excluded worksheets.
auto_clear boolean Filter only true, false Filter action clearing behavior.
fields array Filter only Field refs Explicit linked fields for filter actions. Required when materialize_target_filters is true.
materialize_target_filters boolean Filter only true, false Emits target worksheet filters for linked fields.
field_captions array Highlight only Display field captions Highlight fields by caption. Mutually exclusive with special_fields.
special_fields string Highlight only all Highlight all fields. Mutually exclusive with field_captions.
source_field object Parameter only Aggregate shelf item Source value used to set a parameter.
target_parameter string Parameter only Parameter name Parameter to update.
url string URL only http://... or https://... URI URL opened by the action.
target_sheet string Go-to-sheet only Worksheet or dashboard name Sheet opened by the action.

Action Source And Target

Object Field Required Values Description
source dashboard Yes Dashboard name Dashboard where the action originates.
source worksheet Required for filter, parameter, URL, and go-to-sheet actions Worksheet name Source worksheet.
source exclude Highlight only Worksheet names Source worksheets to exclude.
target dashboard Yes Dashboard name Target dashboard.
target exclude No Worksheet names Target worksheets to exclude.

Action Examples

Filter action:

{
  "name": "Filter Detail From Category",
  "kind": "filter",
  "activation": "select",
  "source": {
    "dashboard": "Sales Dashboard",
    "worksheet": "Sales by Category"
  },
  "target": {
    "dashboard": "Sales Dashboard",
    "exclude": ["Sales by Category"]
  },
  "fields": ["[Orders].[Category]"],
  "materialize_target_filters": true,
  "auto_clear": true
}

Highlight action:

{
  "name": "Highlight Segment",
  "kind": "highlight",
  "activation": "hover",
  "source": {
    "dashboard": "Sales Dashboard",
    "worksheet": "Sales by Category"
  },
  "target": {
    "dashboard": "Sales Dashboard"
  },
  "field_captions": ["Segment"]
}

Parameter action:

{
  "name": "Set Target From Sales",
  "kind": "parameter",
  "activation": "select",
  "source": {
    "dashboard": "Sales Dashboard",
    "worksheet": "Sales by Category"
  },
  "source_field": {
    "field": "[Orders].[Sales]",
    "aggregation": "sum"
  },
  "target_parameter": "Sales Target"
}

URL and go-to-sheet actions:

[
  {
    "name": "Open Sales Details",
    "kind": "url",
    "source": {
      "dashboard": "Sales Dashboard",
      "worksheet": "Sales by Category"
    },
    "url": "https://example.com/sales?segment=consumer"
  },
  {
    "name": "Open Detail Dashboard",
    "kind": "go_to_sheet",
    "source": {
      "dashboard": "Sales Dashboard",
      "worksheet": "Sales by Category"
    },
    "target_sheet": "Detail Dashboard"
  }
]