A library to parse and enumerate powerbi visual settings.
Last updated 3 years ago by stopyoukid .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @essex/visual-settings 
SYNC missed versions from official npm registry.

Essex PBI Base -- Visual Settings

A library to parse/enumerate PowerBI formatting pane settings in a simple way.


See the root README on how to build this project.


Create a Visual Settings class that extends from the visual-settings/HasSettings class, and mark each of your settings that you want to persist into powerbi, with an appropriate setting decorator.

import { HasSettings, boolSetting, numberSetting, textSetting, colorSetting } from "visual-settings";
class MyVisualSettings extends HasSettings {

    @boolSetting({ // Represents a boolean setting (a toggle switch)
        category: "Formatting", // This is the top level grouping within PowerBI's formatting pane
        displayName: "My Bool Setting", // This is the text that gets displayed in the formatting pane for this setting
        description: "Who's setting is it?", // This is the description of this setting, it will be displayed to the users.
        defaultValue: true, // *Optional* This is the default value for this setting if the user hits the reset button.
        enumerable: true, // *Optional* (default: true) If true, the setting will be displayed in the formatting pane, and the user can modify it. If false, it will be a hidden setting that your visual can update, but the user cannot
        persist: true, // *Optional* (default: true) If true, when this settings value has changed, it will be persisted to powerbi.  This config option is handy if you only want to read setting values from PowerBI but not update them.
    public bool myBoolSetting = true;

    @numberSetting({ // Represents a numeric setting
    public number myNumberSetting;

    @textSetting({ // Represents a text/string setting
    public string myTextSetting;

    @colorSetting({ // Represents a color setting (shows a color pallette)
    public string myColorSetting; // This is a hex code string i.e. #cfcfcf

Instantiate your settings class within your visual, and store the current dataView

import MyVisualSettings from "./visualSettings";

class MyVisual implements IVisual {
    private dataView: powerbi.DataView;
    private visualSettings: MyVisualSettings;

    constructor() {
        this.visualSettings = MyVisualSettings.create<MyVisualSettings>();

    public update(options: VisualUpdateOptions) {
        if (options.dataViews && options.dataViews[0]) {
            this.dataView = options.dataViews[0];

        const oldSettings = this.visualSettings; // A reference to the old settings
        this.visualSettings = this.visualSettings.receiveFromPBI(this.dataView); // Parse the new settings from PowerBI

Update your enumerateObjectInstances to return the values from your settings.

import MyVisualSettings from "./visualSettings";

class MyVisual implements IVisual {

    private dataView: powerbi.DataView;
    private visualSettings: MyVisualSettings;

     * The IVisual.enumerateObjectInstances function
     * Enumerates the instances for the objects that appear in the power bi panel
    public enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstance[] {
        return this.visualSettings.buildEnumerationObjects(options.objectName, this.dataView, false);

If you change a settings value and want to persist it back to powerbi

import MyVisualSettings from "./visualSettings";

class MyVisual implements IVisual {
    private visualSettings: MyVisualSettings;
    private host: IVisualHost;
    private dataView: powerbi.DataView;

    public void onUpdateSettingValue(value: string) {
        this.visualSettings.myTextSetting = value;

        const pbiObjects = this.visualSettings.buildPersistObjects(this.dataView);
        this.host.persistProperties(pbiObjects); // Persist them off to powerbi

Current Tags

  • 3.0.0                                ...           latest (2 years ago)

9 Versions

  • 3.0.0                                ...           2 years ago
  • 2.1.3                                ...           2 years ago
  • 2.1.2                                ...           2 years ago
  • 2.1.1                                ...           2 years ago
  • 2.1.0                                ...           2 years ago
  • 2.0.1                                ...           3 years ago
  • 2.0.0                                ...           3 years ago
  • 1.1.1                                ...           3 years ago
  • 1.0.0                                ...           3 years ago
Today 0
This Week 0
This Month 9
Last Day 0
Last Week 9
Last Month 2
Dependencies (10)
Dev Dependencies (0)
Dependents (0)

Copyright 2014 - 2017 © taobao.org |