A parameter is a workbook variable such as a number, date, or string that can replace a constant value in a calculation, filter, or reference line.

For example, you may create a calculated field that returns True if Sales is greater than $500,000 and otherwise returns False. You can replace the constant value of “500000” in the formula with a parameter. Then, using the parameter control, you can dynamically change the threshold in your calculation.

You can even create a dynamic parameter that’s set to automatically refresh its current value (to the result of a single-value, view-independent calculation), list of values (based on a data source column), or range of values. This will happen each time the workbook is opened and Tableau connects to the data source referenced by the parameter, or whenever you select Refresh from the data source’s context menu..

You can make your parameters more dynamic and interactive by using them in Parameter Actions. Parameter actions let your audience change a parameter value through direct interaction with a viz, such as clicking or selecting a mark.

Watch a video: To see related concepts demonstrated in Tableau, watch the free training video Parameters(Link opens in a new window) (5 minutes). Use your tableau.com(Link opens in a new window) account to sign in. For a more in-depth presentation, see Parameters | Oh, the places you'll go!(Link opens in a new window) (45 minutes).

Learn more: See Use Parameters to Add Multiple Views to Your Viz(Link opens in a new window) on the Tableau blog(Link opens in a new window) and multiple practical topics on how to use parameters(Link opens in a new window) on the Data School(Link opens in a new window) website, such as Four Steps to Creating a Parameter(Link opens in a new window).

Create a parameter

Follow the instructions below to create a new parameter from the Data pane.

  1. In the Data pane, click the drop-down arrow in the upper right corner and select Create Parameter.

  2. In the Create Parameter dialog box, give the field a Name.

  3. Specify the data type for the values it will accept:

  4. Specify a current value. This is the default value for the parameter. In this case, let’s leave the field as is because we’ll be using the latest data, which we’ll configure in the next step.

  5. Specify a value when the workbook opens. In this case, let’s create a dynamic parameter by setting the parameter’s default value to the result of a single-value, view-independent calculation.

    Note: If there is more than one value, the workbook would not be able to choose a default value. The calculation must also be view-independent so that the value won’t change as the viz changes. To do this, you can use a FIXED level of detail (LOD) expression that is not dependent on the structure of the viz. All parts of the calculation must be inside the FIXED LOD expression. If you use a FIXED LOD expression as the default value and are using context filters, the dynamic parameter will not reflect any context filters. For more information on LOD expressions, see Create Level of Detail Expressions in Tableau.

    For this dynamic parameter, let's use Latest Month. This means that if the connected data source is updated and the workbook is opened, the parameter will automatically update when the workbook is opened.

  6. Specify the display format to use in the parameter control (Tableau Desktop only).

  7. Specify how the parameter will accept values. You can select from the following options:

    • All - The parameter control is a simple text field.

    • List - The parameter control provides a list of possible values for you to select from.

    • Range - The parameter control lets you select values within a specified range.

    The availability of these options is determined by the data type. For example, a string parameter can only accept all values or a list. It does not support a range.

    If you select List, you must specify the list of values. Click in the left column to type your list of values, or you can add members of a field by selecting Add values from.

    If you select Range, you must specify a minimum, maximum, and step size. For example, you can define a date range between January 1, 2019 and December 31, 2019, with the step size set to 1 month to create a parameter control that lets you select each month in 2019.

    In this case, to refresh the parameter’s list of values (or domain) whenever the workbook opens, select List, and then select When workbook opens. Notice that the list of values on the left is grayed out because the workbook is dynamically pulling values from the data source.

  8. When finished, click OK.

    The parameter is now listed in the Parameters section at the bottom of the Data pane.

    The parameter is also available everywhere else you can use a parameter—for example, on the Top tab in the Filter dialog box, or in the Reference Line dialog box. Parameters are global across the workbook and can be used in any worksheet.

When the parameter value or list of values can’t refresh

Below are a few scenarios in which a default parameter value or a refreshable list of parameter values (domain) will not update as expected:

  • The default field returns a value whose data is incompatible with the parameter’s data type.

  • The default field doesn’t return a single value (for the parameter’s current value).

  • The default field returns null.

  • The default field is in a data source that’s not yet connected.

  • The default field is no longer found in the workbook’s namespace (i.e. it’s been deleted).

  • The user cancels the query to the data source while Tableau is attempting to connect.

Note: On Desktop, these queries are initially evaluated when the workbook is opened and Tableau connects to the fields’ data sources for the first time. You can also evaluate the queries by refreshing the data source. To do this, press F5, or open the data source’s context menu and select Refresh. On Server and Online, you can refresh the data source by clicking the Data Source Refresh button in the toolbar. In this case, however, remember that the value returned depends on the server's cache policies.

If the default fields fail to return values, the parameter will behave as follows:

  • The current value will keep the latest valid value.
  • The list of values will be empty because Tableau doesn’t serialize the values returned from the query in the workbook.

The current value must be in the list of values for it to be assigned to the parameter. If the list of values is empty, the parameter will get assigned a fallback value according to the data type (1 for integer, 1.0 for float, "" for string, and the current date for date and datetime).

Edit a parameter

You can edit parameters from the Data pane or the parameter control. Follow the instructions below to edit a parameter:

  1. Do one of the following:

    • Right-click (Control-click on a Mac) the parameter in the Data pane and select Edit.

    • Select Edit Parameter on the parameter control card menu.

  2. In the Edit Parameter dialog box, make the modifications as necessary.

  3. When finished, click OK. The parameter is updated along with any calculations that use it.

To delete a parameter, right-click it in the Data pane and select Delete. Any calculated fields that use the deleted parameter will become invalid.

Use a parameter in a calculation

Parameters give you a way to dynamically modify values in a calculation. Rather than manually editing the calculation (and all dependent calculations), you can use a parameter. Then when you want to change the value, you open the parameter control, change the value, and all of the calculations that use that parameter are updated.

To use a parameter in a calculation, drag the parameter from the Data pane and drop it in the calculation editor, either at a new location in the formula or to replace a part of the current formula:

Use a parameter in a filter

Parameters give you a way to dynamically modify values in a Top N filter. Rather than manually setting the number of values you want to show in the filter, you can use a parameter. Then when you want to change the value, you open the parameter control and the filter updates. For example, when creating a filter to show the Top 10 products based on total profit, you may want to use a parameter instead of the fixed “10” value. That way, you can quickly update the filter to show the top 10, 20, or 30 products.

A list of parameters is available in the drop-down lists on the Top tab of the Filter dialog box. Select the parameter you want to use in the filter.

To show the parameter control, right-click the parameter in the Data pane and select Show Parameter. Use the parameter control to modify the filter to show the top 10 products, 15 products, 20 products, and so on.

Use a parameter in a reference line

Parameters give you a way to dynamically modify a reference line, band, or box. For example, instead of showing a reference line at a fixed location on the axis, you can reference a parameter. Then you can use the parameter control to move the reference line.

A list of parameters is available in the Value drop-down list in the Add Reference Line, Band, or Box dialog box. Select the parameter you want to use.

The reference line is drawn at the Current Value specified by the parameter. To open the parameter control, right-click (Control-click on a Mac) the parameter in the Data pane and then select Show Parameter. Use the parameter control to change where the reference line is drawn.

Show a parameter control in the viz

The parameter control is a worksheet card that lets you modify the parameter value. Parameter controls are very similar to filter cards in that they contain controls that modify the view. You can open parameter controls on worksheets and dashboards and they are included when you save to the web or publish to Tableau Server.

To open the parameter control, right-click (Control-click) the parameter in the Data pane and select Show Parameter.

Like other cards, parameter controls have a menu that you can open using the drop-down arrow in the upper right corner of the card. Use this menu to customize the display of the control. For example, you can show a list of values as radio buttons, a compact list, a slider, or a type in field. The options available on this menu depend on the data type of the parameter as well as whether it accepts all, a list, or a range of values.