Color utils

Article
01/25/2023

This article will help you to install, import, and use color utils. Learn how to use color utils to apply themes and palettes on a Power BI visual's data points.

Prerequisites

To use the package, install:

node.js (we recommend the latest LTS version)
npm (the minimal supported version is 3.0.0)
The custom visual created by PowerBI-visuals-tools

Installation

To install the package, you should run the following command in the directory with your current visual:

npm install powerbi-visuals-utils-colorutils --save

This command installs the package and adds a package as a dependency to your package.json file.

Usage

To use interactivity utils, you have to import the required component in the source code of the visual.

import { ColorHelper } from "powerbi-visuals-utils-colorutils";

Learn how to install and use the colorUtils in your Power BI visuals:

[Usage Guide] The Usage Guide describes a public API of the package. It provides a description and examples for each public interface.

This package contains the following classes and modules:

ColorHelper - helps to generate different colors for your chart values
colorUtils - helps to convert color formats

ColorHelper

The ColorHelper class provides the following functions and methods:

getColorForSeriesValue

This method gets the color for a specific series value. If no explicit color or default color has been set, then the color is allocated from the color scale for this series.

getColorForSeriesValue(objects: IDataViewObjects, value: PrimitiveValue, themeColorName?: ThemeColorName): string;

getColorForSeriesValue example

import powerbi from "powerbi-visuals-api";
import { ColorHelper } from "powerbi-visuals-utils-colorutils";

import DataViewObjects = powerbi.DataViewObjects;

import DataViewValueColumns = powerbi.DataViewValueColumns;
import DataViewValueColumnGroup = powerbi.DataViewValueColumnGroup;
import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;

import IVisual = powerbi.extensibility.visual.IVisual;
import IColorPalette = powerbi.extensibility.IColorPalette;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;

export class YourVisual implements IVisual {
    // Implementation of IVisual

    private colorPalette: IColorPalette;

    constructor(options: VisualConstructorOptions) {
        this.colorPalette = options.host.colorPalette;
    }

    public update(visualUpdateOptions: VisualUpdateOptions): void {
        const valueColumns: DataViewValueColumns = visualUpdateOptions.dataViews[0].categorical.values,
            grouped: DataViewValueColumnGroup[] = valueColumns.grouped(),
            defaultDataPointColor: string = "green",
            fillProp: DataViewObjectPropertyIdentifier = {
                objectName: "objectName",
                propertyName: "propertyName"
            };

        let colorHelper: ColorHelper = new ColorHelper(
            this.colorPalette,
            fillProp,
            defaultDataPointColor);

        for (let i = 0; i < grouped.length; i++) {
            let grouping: DataViewValueColumnGroup = grouped[i];

            let color = colorHelper.getColorForSeriesValue(grouping.objects, grouping.name); // returns a color of the series
        }
    }
}

getColorForMeasure

This method gets the color for a specific measure.

 getColorForMeasure(objects: IDataViewObjects, measureKey: any, themeColorName?: ThemeColorName): string;

Get color for measure example

import powerbi from "powerbi-visuals-api";
import { ColorHelper } from "powerbi-visuals-utils-colorutils";

import DataViewObjects = powerbi.DataViewObjects;
import IVisual = powerbi.extensibility.visual.IVisual;
import IColorPalette = powerbi.extensibility.IColorPalette;
import VisualUpdateOptions = powerbi.extensibility.visual.VisualUpdateOptions;
import DataViewObjectPropertyIdentifier = powerbi.DataViewObjectPropertyIdentifier;
import VisualConstructorOptions = powerbi.extensibility.visual.VisualConstructorOptions;

export class YourVisual implements IVisual {
    // Implementation of IVisual

    private colorPalette: IColorPalette;

    constructor(options: VisualConstructorOptions) {
        this.colorPalette = options.host.colorPalette;
    }

    public update(visualUpdateOptions: VisualUpdateOptions): void {
        const objects: DataViewObjects = visualUpdateOptions.dataViews[0].categorical.categories[0].objects[0],
            defaultDataPointColor: string = "green",
            fillProp: DataViewObjectPropertyIdentifier = {
                objectName: "objectName",
                propertyName: "propertyName"
            };

        let colorHelper: ColorHelper = new ColorHelper(
            this.colorPalette,
            fillProp,
            defaultDataPointColor);

        let color = colorHelper.getColorForMeasure(objects, ""); // returns a color
    }
}

static `normalizeSelector`

This method returns the normalized selector.

static normalizeSelector(selector: Selector, isSingleSeries?: boolean): Selector;

static normalizeSelector example

import ISelectionId = powerbi.visuals.ISelectionId;
import { ColorHelper } from "powerbi-visuals-utils-colorutils";

let selectionId: ISelectionId = ...;
let selector = ColorHelper.normalizeSelector(selectionId.getSelector(), false);

Methods getThemeColor and getHighContrastColor are both related to color theme colors. ColorHelper has the isHighContrast property.

`getThemeColor`

This method returns the theme color.

 getThemeColor(themeColorName?: ThemeColorName): string;

`getHighContrastColor`

This method returns the color for high-contrast mode.

getHighContrastColor(themeColorName?: ThemeColorName, defaultColor?: string): string;

High-contrast mode example


import { ColorHelper } from "powerbi-visuals-utils-colorutils";

export class MyVisual implements IVisual {
        private colorHelper: ColorHelper;

        private init(options: VisualConstructorOptions): void {
            this.colors = options.host.colorPalette;
            this.colorHelper = new ColorHelper(this.colors);
        } 

            private createViewport(element: HTMLElement): void {
                const fontColor: string = "#131aea";
                const axisBackgroundColor: string = this.colorHelper.getThemeColor();
                
                // some d3 code before
                d3ElementName.attr("fill", colorHelper.getHighContrastColor("foreground", fontColor);
            }
                
            public static parseSettings(dataView: DataView, colorHelper: ColorHelper): VisualSettings {
                // some code that should be applied on formatting settings
                if (colorHelper.isHighContrast) {
                        this.settings.fontColor = colorHelper.getHighContrastColor("foreground", this.settings.fontColor);
                    }
            }
}

`ColorUtils`

The module provides the following functions:

hexToRGBString
rotate
parseColorString
calculateHighlightColor
createLinearColorScale
shadeColor
rgbBlend
channelBlend
hexBlend

hexToRGBString

Converts a hex color to an RGB string.

function hexToRGBString(hex: string, transparency?: number): string

hexToRGBString example

import  { hexToRGBString } from "powerbi-visuals-utils-colorutils";

hexToRGBString('#112233');

// returns: "rgb(17,34,51)"

rotate

Rotates RGB color.

function rotate(rgbString: string, rotateFactor: number): string

rotate example

import { rotate } from "powerbi-visuals-utils-colorutils";

rotate("#CC0000", 0.25); // returns: #66CC00

parseColorString

Parses any color string to RGB format.

function parseColorString(color: string): RgbColor

parseColorString example

import { parseColorString } from "powerbi-visuals-utils-colorutils";

parseColorString('#09f');
// returns: {R: 0, G: 153, B: 255 }

parseColorString('rgba(1, 2, 3, 1.0)');
// returns: {R: 1, G: 2, B: 3, A: 1.0 }

calculateHighlightColor

Calculates the highlight color from the rgbColor based on the lumianceThreshold and delta.

function calculateHighlightColor(rgbColor: RgbColor, lumianceThreshold: number, delta: number): string

calculateHighlightColor example

import { calculateHighlightColor } from "powerbi-visuals-utils-colorutils";

let yellow = "#FFFF00",
    yellowRGB = parseColorString(yellow);

calculateHighlightColor(yellowRGB, 0.8, 0.2);

// returns: '#CCCC00'

createLinearColorScale

Returns a linear color scale for a specific domain of numbers.

function createLinearColorScale(domain: number[], range: string[], clamp: boolean): LinearColorScale

createLinearColorScale example

import { createLinearColorScale } from "powerbi-visuals-utils-colorutils";

let scale = ColorUtility.createLinearColorScale(
    [0, 1, 2, 3, 4],
    ["red", "green", "blue", "black", "yellow"],
    true);

scale(1); // returns: green
scale(10); // returns: yellow

shadeColor

Converts a string hex expression to a number, and calculates the percentage and R, G, B channels. Applies the percentage for each channel and returns the hex value as a string with a pound sign.

function shadeColor(color: string, percent: number): string

shadeColor example

import { shadeColor } from "powerbi-visuals-utils-colorutils";

shadeColor('#000000', 0.1); // returns '#1a1a1a'
shadeColor('#FFFFFF', -0.5); // returns '#808080'
shadeColor('#00B8AA', -0.25); // returns '#008a80'
shadeColor('#00B8AA', 0); // returns '#00b8aa'

rgbBlend

Overlays a color with opacity over a background color. Any alpha-channel is ignored.

function rgbBlend(foreColor: RgbColor, opacity: number, backColor: RgbColor): RgbColor

rgbBlend example

import { rgbBlend} from "powerbi-visuals-utils-colorutils";

rgbBlend({R: 100, G: 100, B: 100}, 0.5, {R: 200, G: 200, B: 200});

// returns: {R: 150, G: 150, B: 150}

channelBlend

Blends a single channel for two colors.

function channelBlend(foreChannel: number, opacity: number, backChannel: number): number

channelBlend example

import { channelBlend} from "powerbi-visuals-utils-colorutils";

channelBlend(0, 1, 255); // returns: 0
channelBlend(128, 1, 255); // returns: 128
channelBlend(255, 0, 0); // returns: 0
channelBlend(88, 0, 88); // returns: 88

hexBlend

Overlays a color with opacity over a background color.

function hexBlend(foreColor: string, opacity: number, backColor: string): string

hexBlend example

import { hexBlend} from "powerbi-visuals-utils-colorutils";

let yellow = "#FFFF00",
    black = "#000000",
    white = "#FFFFFF";

hexBlend(yellow, 0.5, white); // returns: "#FFFF80"
hexBlend(white, 0.5, yellow); // returns: "#FFFF80"

hexBlend(yellow, 0.5, black); // returns: "#808000"
hexBlend(black, 0.5, yellow); // returns: "#808000"