Control report slicers

  • Article

Using the slicer APIs, you can get and set the state of a Power BI slicer. In addition, you can use load configuration to change the slicer state when loading a report.

There are two type of slicer visuals:

  • Out-of-the-box - Slicers for out-of-the-box Power BI visuals. Out-of-the-box slicers support all the Power BI visuals that are shipped with Power BI (Desktop and service).

  • Power BI visuals from AppSource and files - Slicers for third party Power BI visuals, available from AppSource, or as a .pbiviz file. Slicers for Power BI visuals from AppSource and files, or in short visuals from AppSource or files, are slicers for Power BI visuals built by developers.

Slicer object

There are four slicer types:

Categorical slicer

Categorical slicers support the following displays:

  • A list
  • A dropdown menu
  • Value cards

You can select single or multiple items from these lists to filter the report accordingly.

To change a selection for these type of slicers, you need to create an IBasicFilter object. For more information about creating a basic filter, see Basic filter.

const basicFilter = {
  $schema: "http://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    column: "Count"
  },
  operator: "In",
  values: [1, 2, 3, 4],
  filterType: models.FilterType.BasicFilter
};

await visual.setSlicerState({
    filters: [basicFilter]
});

If the slicer target is a hierarchy, provide an IFilterHierarchyTarget target. For more information, see Use targets to select which data field to act on.

const basicFilter = {
  $schema: "http://powerbi.com/product/schema#basic",
  target: {
    table: "Store",
    hierarchy: "Country",
    hierarchyLevel: "Code"
  },
  operator: "In",
  values: [456, 943],
  filterType: models.FilterType.BasicFilter
};

await visual.setSlicerState({
    filters: [basicFilter]
});

Range slicer

Range slicers support conditions such as:

  • Between
  • Before
  • After

To change a selection for range slicers, create an IAdvancedFilter object. For more information, see Advanced filter.

const advancedFilter = {
  $schema: "http://powerbi.com/product/schema#advanced",
  target: {
    table: "Store",
    column: "Number"
  },
  logicalOperator: "And",
  conditions: [
    {
      operator: "GreaterThanOrEqual",
      value: 30
    },
    {
      operator: "LessThan",
      value: 40
    }
  ],
  filterType: models.FilterType.AdvancedFilter
};

await visual.setSlicerState({
    filters: [advancedFilter]
});

Relative date slicer

Relative date slicers support conditions such as:

  • Last Week
  • Last five years

To change a selection for relative date slicers, create an IRelativeDateFilter object. For more information, see Relative date and relative time filter objects.

const relativeDateFilter = {
  $schema: "http://powerbi.com/product/schema#relativeDate",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 30,
  timeUnitType: models.RelativeDateFilterTimeUnit.Days,
  includeToday: true,
  filterType: models.FilterType.RelativeDate
};

await visual.setSlicerState({
    filters: [relativeDateFilter]
});

Relative time slicer

Relative time slicers support conditions such as:

  • Last five minutes
  • This hour

To change a selection for relative time slicers, create an IRelativeTimeFilter object. For more information, see Relative date and relative time filters.

const relativeTimeFilter = {
  $schema: "http://powerbi.com/product/schema#relativeTime",
  target: {
    table: "Sales",
    column: "OrderDate"
  },
  operator: models.RelativeDateOperators.InLast,
  timeUnitsCount: 5,
  timeUnitType: models.RelativeDateFilterTimeUnit.Minutes,
  filterType: models.FilterType.RelativeTime
};

await visual.setSlicerState({
    filters: [relativeTimeFilter]
});

Hierarchy slicer

Hierarchy slicers let you filter from multiple related fields.

Screenshot showing an example of a hierarchy slicer. It shows the levels year, quarter, and month.

The Hierarchy slicer is supported from SDK version 2.21. Set selections in the hierarchy slicer with the setSlicerState API or get the current hierarchy selections with getSlicerState API.

Read about adding fields to hierarchy slicers.

Hierarchy filter

The IHierarchyFilter describes the slicer hierarchy. Use the getSlicerState and setSlicerState methods with this filter.

interface IHierarchyFilter extends IFilter {
    target: (IFilterTarget | IFilterKeyTarget)[];
    hierarchyData: IHierarchyFilterNode[];
}

  • hierarchyData - the selected and unselected items in a hierarchy tree where each IHierarchyFilterNode represents a single value selection.

    interface IHierarchyFilterNode {
    value?: PrimitiveValueType;
    keyValues?: PrimitiveValueType[];
    children?: IHierarchyFilterNode[];
    operator?: HierarchyFilterNodeOperators;
}
    • Either value or keyValues must be set
    • children – List of the node children relevant to the current selection
    • operator – The operator for single objects in the tree. The operator can be one of the following:

    type HierarchyFilterNodeOperators = "Selected" | "NotSelected" | "Inherited";

    • Selected – value is explicitly selected.
    • NotSelected – value is explicitly not selected.
    • Inherited – value selection is according to the parent value in the hierarchy, or default if it's the root value.

    operator is optional. If no operator is set, the default is Inherited.

Hierarchy slicer examples

The following examples describe different scenarios for using the setSlicerState API with hierarchy slicers.

  • Select values on different levels. For example, select ‘Qtr 1’ and ‘Qtr 2’ in 2013 and ‘Qtr 1’ and ‘Qtr 2’ in 2014.

    const filter = {
  "$schema": http://powerbi.com/product/schema#hierarchy,
  "target": [
      {
          "table": "Dates",
          "hierarchy": "Date Hierarchy",
          "hierarchyLevel": "Year"
      },
      {
          "table": "Dates",
          "hierarchy": "Date Hierarchy",
          "hierarchyLevel": "Quarter"
      }
  ],
  "filterType": 9,
  "hierarchyData": [
      {
          "operator": "Inherited",
          "value": 2013,
          "children": [
              {
                  "operator": "Selected",
                  "value": "Qtr 1"
              },
              {
                  "operator": "Selected",
                  "value": "Qtr 2"
              }
          ]
      },
      {
          "operator": "Inherited",
          "value": 2014,
          "children": [
              {
                  "operator": "Selected",
                  "value": "Qtr 1"
              },
              {
                  "operator": "Selected",
                  "value": "Qtr 2"
              }
          ]
      }
  ]
};

await slicer.setSlicerState({ filters: [filter] });

    Screenshot showing an example of a hierarchy slicer with quarters one and two selected for years 2013 and 2014.

  • Select values on different levels with exceptions. For example, select 2014 without ‘Qtr 1’.

    const filter = {
  "$schema": http://powerbi.com/product/schema#hierarchy,
  "target": [
      {
          "table": "Dates",
          "hierarchy": "Date Hierarchy",
          "hierarchyLevel": "Year"
      },
      {
          "table": "Dates",
          "hierarchy": "Date Hierarchy",
          "hierarchyLevel": "Quarter"
      }
  ],
  "filterType": 9,
  "hierarchyData": [
      {
          "operator": "Selected",
          "value": 2014,
          "children": [
              {
                  "operator": "NotSelected",
                  "value": "Qtr 1"
              }
          ]
      }
  ]
};

await slicer.setSlicerState({ filters: [filter] });

    Screenshot showing an example of a hierarchy slicer selecting values at different levels with exceptions. It has the year 2014 selected except for Q 1.

  • Start with the NotSelected operator to select everything except for certain values. For example, select everything except for ‘Qtr 1’ of 2008, and 2009.

    const filter = {
  "$schema": http://powerbi.com/product/schema#hierarchy,
  "target": [
      {
          "table": "Dates",
          "column": "Year"
      },
      {
          "table": "Dates",
          "column": "Quarter"
      }
  ],
  "filterType": 9,
  "hierarchyData": [
      {
          "operator": "NotSelected",
          "value": 2009
      },
      {
          "operator": "Inherited",
          "value": 2008,
          "children": [
              {
                  "operator": "NotSelected",
                  "value": "Q1"
              }
          ]
      }
  ]
}

await slicer.setSlicerState({ filters: [filter] });

    Screenshot showing an example of a hierarchy slicer selecting everything except for specified values. Years 2010 through 2014 are selected. 2008 is selected without Q 1 and 2009 is not selected at all.

Slicer APIs

You can use the following methods for visuals with the slicer type:

Note

Sync slicers configuration saved in a report is recognized by the slicer APIs. This means that if you set a slicer using the API, all slicers in the same sync group will be affected.

Get slicer state

To get a slicer state, you need to find the slicer visual instance and call getSlicerState. The result is of type ISlicerState.

By default, the slicer will not have any filters applied to it. In such cases, getSlicerState will return ISlicerState with an empty array of filters.

getSlicerState works for both out-of-the-box and visuals from AppSource or files slicers.

let state = await visual.getSlicerState();

Set slicer state

To set a slicer state, you need to find the slicer visual instance, create the slicer state and call setSlicerState with the slicer state you created.

await visual.setSlicerState(state);

The slicer state is an ISlicerState object.

interface ISlicerState {
    filters: ISlicerFilter[];
    targets?: SlicerTarget[];
}

To reset a slicer, call setSlicerState with an empty array of filters.

Setting a slicer for visuals from AppSource or files

To set a visuals from AppSource or files slicer selection, you need to create an ISlicerFilter object, which can be of the following types:

  • IBasicFilter
  • IAdvancedFilter
  • IRelativeDateFilter
  • IRelativeTimeFilter

Different visuals from AppSource or files slicers, support different types of filters. To determine the filter type required to modify the slicer, call visual.getSlicerState().

For more information about filter types, see Control report filters.

Setting slicers on report load

Report load configuration supports changing slicers state. This allows you to change the report slicers state during report load. To do this, pass an ISlicer array.

interface IReportLoadConfiguration {
    ...
    slicers?: ISlicer[];
}

Each ISlicer object contains a selector and a slicer state.

interface ISlicer {
    selector: SlicerSelector;
    state: ISlicerState;
}

Use a visual name or slicer target selector to select which slicer to change. For more information, see Use selectors to control which visuals are effected.

Note

If you pass different ISlicer objects that are in the same sync group, the result will be unexpected.

Apply slicer on load examples

This section includes two examples of load configuration with slicers.

  • Set a specific slicer by name

    let slicers = [
  {
    selector: {
      $schema: "http://powerbi.com/product/schema#visualSelector",
      visualName: "d1feb8891635af3b335a"
    },
    state: {
      filters: [advancedFilter]
    }
  }
];

let embedConfig = {
  ...
  slicers: slicers,
};

  • Set slicers by slicer target

    let target = {
  table: "Store",
  column: "StoreNumber"
};

let slicers = [
  {
    selector: {
      $schema: "http://powerbi.com/product/schema#slicerTargetSelector",
      target: target 
    },
    state: {
      filters: [advancedFilter]
    }
  }
];

let embedConfig = {
  ...
  slicers: slicers,
};

Considerations and limitations

  • Tuple slicers are not supported.

  • The Hierarchy slicer is supported from SDK version 2.21.

  • Out-of-the-box slicers support only a single filter.

  • Calling setSlicerState on a visual which is not a slicer, will return a rejected promise with the error Operation works on slicers only.

  • There is no API to change the slicers sync configuration.

Next steps