Use selectors to control which visuals are effected

  • Article

Some features allow you to use selectors to control which visuals are effected. The selector is optional, and when it doesn't appear, the settings are applicable for all the visuals in the report.

Supported features

Selectors can be used in the following features:

Selector types

Visual name

Apply the settings only for the specified visual.

selector: {
    $schema: "http://powerbi.com/product/schema#visualSelector",
    visualName: <a visual name> // You can retrieve the name using `getVisuals`
}

In order to find a visual name, you can use the getVisuals() API on a page and get the visual's name property. Visual name is a unique identifier.

Visual type

Apply the settings to all the visuals from the specified type.

selector: {
    $schema: "http://powerbi.com/product/schema#visualTypeSelector",
    visualType: <a visual type> // You can retrieve the type using `getVisuals`
}

In order to find a visual type, you can use the getVisuals() API on a page and get the visual's type property.

Slicer target

Apply the slicer state only for the slicers with the specified target.

selector: {
    $schema: "http://powerbi.com/product/schema#slicerTargetSelector",
    target: <target data field>  
}

Examples

Visual header settings

  • Hide all visual headers in the report.

    let config = {
    …
    settings: {
        …
        visualSettings: {
            visualHeaders: [
                {
                    settings: {
                        visible: false
                    }
                    /* No selector - Hide visual header for all the visuals in the report */
                }
            ]
        }
    }
};

  • Hide a visual header for a specific visual using the visual selector.

    let config = {
    …
    settings: {
        …
        visualSettings: {
            visualHeaders: [
                {
                    settings: {
                        visible: false
                    }
                    selector: {
                        $schema: "http://powerbi.com/product/schema#visualSelector",
                        visualName: "VisualContainer1",
                    }
                }
            ]
        }
    }
};

Both menu command extensions and built-in commands display support selectors.

  • Adding an extension command to a specific visual options menu.

    let config = {
    ...
    settings: {
        ...

        // Adding the extension command to the options menu
        extensions: [
            {
                command: {
                    name: "campaign",
                    title: "Start campaign",
                    icon: base64Icon,
                    selector: {
                        $schema: "http://powerbi.com/product/schema#visualSelector",
                        visualName: tableVisualName
                    },
                    extend: {
                        visualOptionsMenu: {
                            title: "Start campaign",
                            menuLocation: models.MenuLocation.Top,
                        }
                    }
                }
            },
        ],
    }
}

  • Hide a few built-in commands for all visuals with table type.

    let tableSelector = {
    $schema: "http://powerbi.com/product/schema#visualTypeSelector",
    visualType: 'table'
};

let config = {
    ...
    settings: {
        ...
        // Hiding built-in commands on the options menu
        commands: [
            {
                spotlight: {
                    selector: tableSelector,
                    displayOption: models.CommandDisplayOption.Hidden,
                },
                exportData: {
                    selector: tableSelector,
                    displayOption: models.CommandDisplayOption.Hidden,
                },
                seeData: {
                    selector: tableSelector,
                    displayOption: models.CommandDisplayOption.Hidden,
                },
            }
        ]
    },
};

Slicers on load

Note

Slicers on load do not support visual type selector

  • Set a specific slicer by name

    let slicers = [
    {
        selector: {
            $schema: "http://powerbi.com/product/schema#visualSelector",
            visualName: "d1feb8891635af3b335a"
        },
        state: {
            filters: [
            {
                $schema:"http://powerbi.com/product/schema#advanced",
                target: {
                    table: "Store",
                    column: "StoreNumber"
                },
                filterType: models.FilterType.AdvancedFilter,
                logicalOperator: "And",
                conditions: [
                    { operator: "GreaterThanOrEqual", value: 37 },
                    { operator: "LessThanOrEqual", value: 576 }]
            }]
        }
    }
];

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

  • Set slicers by target

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

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

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

Next steps

Modify menu commands for a report visual

Hide or show a visual header

Control report slicers