Skip to content

Slicers

Jump to bottom
Amit Shuster edited this page Jan 24, 2021 · 17 revisions
ℹ️ This wiki has been deprecated
All our Client APIs documentation and references can be found in the new Power BI embedded analytics Client APIs documentation set.
For the content of this article see Control report slicers.

Using slicer APIs, You can get and set slicers state. In addition, you can use load config to change the slicer state when loading a report.

You may want to read the slicer documentation about using slicers in Power BI.

Slicer state

Slicer state contains the filters applied by the slicer. Support types of filter are:

  1. Basic filters.
  2. Basic filters with Keys.
  3. Advanced filters.
  4. Relative date filters.

You can read more about filter interfaces and filter target interfaces in the Filters Documentation.

type ISlicerFilter = IBasicFilter | IBasicFilterWithKeys | IAdvancedFilter | IRelativeDateFilter;
type SlicerTarget = IFilterTarget | IFilterKeyTarget;

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

Example of slicer state

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

Slicer APIs

Slicer APIs have methods which allow you to get and set slicer state.

getSlicerState(): Promise<models.ISlicerState>;
setSlicerState(state: models.ISlicerState): Promise<void>;

Get Slicer state

To get a slicer state you need to find the slicer visual and call a method called getSlicerState on this visual.

visual.getSlicerState()
 .then(state => {
     ...
 });

The result is of type ISlicerState. You can find an example of ISlicerState above.

Default state case

If the slicer is in default state (i.e. no filter applied), getSlicerState will return ISlicerState with an empty array of filters.

Set Slicer state

To set a slicer state you need to create a slicer state object, find the slicer visual and call setSlicerState with the slicer state you created. To reset a slicer, just call setSlicerState with an empty array of filters.

visual.setSlicerState(state)
  .catch(errors => {
    // Handle error
  });

Native slicers

Categorical slicers

This type of slicer supports displaying a list, dropdown or cards of values, where you can select single or multiple items to filter the report accordingly.

To change a selection for these types of slicers you need to create an IBasicFilter object. example:

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

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

If the slicer target is a hierarchy, you need to provide a target of type IFilterHierarchyTarget. example:

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

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

Range slicers

Range slicers support conditions such as: Between, Before, After, .. To change a selection for range slicers you need to create an IAdvancedFilter object. example:

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: pbi.models.FilterType.AdvancedFilter
};

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

Relative date slicers

Relative date slicers support conditions such as: Last Week, Last 5 Years, ... To change a selection for Relative date slicers you need to create an IRelativeDateFilter object. example:

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

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

Again, You can read more about creating filter object in the filters documentation.

Custom visual slicers

To get custom slicer selection, call getSlicerState. This works the same as in native slicers. To set custom slicer selection, you need to create an object of type ISlicerFilter, which can be of the following types: IBasicFilter, IAdvancedFilter and more. see above.

Different custom visual slicers support different types of filters. To determine the filter type required to modify the slicer, you should call visual.getSlicerState().

Setting Slicers on report load

report load configuration supports modifying slicers state. This way, you can modify each slicer by id on report load. To do this, you should pass an array of ISlicer, where each ISlicer contains a slicer selector and a slicer state. The slicer selector selects a slicer to change.

interface ISlicer {
  // Selects a slicer to change.
  selector: SlicerSelector;

  // A new state of the slicer
  state: ISlicerState;
}

// Use slicers parameter in load config to set slicers on load.
interface IReportLoadConfiguration {
  ...
  slicers?: ISlicer[];
  ...
}

SlicerSelector

SlicerSelector is used in order to select slicers to apply the changes on. There are two types of SlicerSelector:

  • IVisualSelector: selects a slicer by a visual unique name.
  • ISlicerTargetSelector: selecs a slicer by a target.
interface ISelector {
  $schema: string;
}

interface IVisualSelector extends ISelector {
    // For visual selector, please use this $schema: http://powerbi.com/product/schema#visualSelector
    visualName: string;
}

interface ISlicerTargetSelector extends ISelector {
    // For slicer target selector, please use this $schema: http://powerbi.com/product/schema#slicerTargetSelector
    target: SlicerTarget;
}

Examples of load configuration with slicers

Set a specific slicer by name

// We want to slice all store number slicers
let target = {"table":"Store","column":"StoreNumber"};

let slicers = [
  {
    selector: {
      $schema: "http://powerbi.com/product/schema#visualSelector",
      visualName: "d1feb8891635af3b335a"
    },
    state: {
      filters: [
        {
          "$schema":"http://powerbi.com/product/schema#advanced",
          "target":target ,
          "filterType":0,
          "logicalOperator":"And",
          "conditions":[{"operator":"GreaterThanOrEqual","value":37.0000001},{"operator":"LessThanOrEqual","value":575.9999999}]
        }
      ]
    }
  }
];

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

Set slicers by target

let slicers = [
  {
    selector: {
      $schema: "http://powerbi.com/product/schema#slicerTargetSelector",
      target: target 
    },
    state: {
      filters: [
        {
          "$schema":"http://powerbi.com/product/schema#advanced",
          "target":target ,
          "filterType":0,
          "logicalOperator":"And",
          "conditions":[{"operator":"GreaterThanOrEqual","value":37.0000001},{"operator":"LessThanOrEqual","value":575.9999999}]
        }
      ]
    }
  }
];

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

Note

If you pass different ISlicer objects on load, and they are in the same sync group, the result will be unexpected.

Sync Slicers

There is no API to change the slicers sync configuration. But, sync configuration saved in the report will be respected in slicer APIs. This means, if you set a slicer through the API, all slicers in the same sync group will be affected.

Further details about slicers sync can be found in the slicers documentation

Limitations

  • The native hierarchy slicer is not yet supported.
  • Native slicers support only single filter.
  • Calling setSlicerState on a visual which is not a slicer will return a rejected promise with an error: “Operation works on slicers only”.
Clone this wiki locally