Flourish colors

Add settings and logic to easily add custom colors to your template

Install

npm install @flourish/colors

Unit tests

Test using:

npm run test

Test a specific test file using:

npm run test test/name-of-test.test.mjs

Basic usage

The settings.yml file should be imported into your template’s template.yml file, like this:

  - Colours
  - property: color
    import: "@flourish/colors"

You can use overrides to control whether to show categorical or numerical color settings. See below for an example. Replace [dataset] and [binding] with the relevant dataset and binding name (learn more about conditional settings).

  - Colours
  - property: color
    import: "@flourish/colors"
    overrides:
      - tag: discrete
        method: extend
        show_if:
          data.[dataset].[binding].type: string
      - tag: numeric
        method: extend
        show_if:
          data.[dataset].[binding].type: number

Add a color object to your template state:

export var state = {
    color: {},
    ...
}

Import the package like import createColors from "@flourish/colors"

var colors = createColors(state.color) creates a new object colors.

You only need to pass in a state to get the color function working.

Methods

colors.getColor(value) finds the correct color for value. Will just return the fallback value unless the updateColorScale method has been called at some point.

colors.fallback([value]) returns the current fallback value if value is undefined or (usually) sets it to value if it is defined and returns the colors object. The value "default" (re)sets the fallback to be the default value of null. The fallback value is returned whenever the getColor method cannot interpret the value passed into it (for example if that value is non-numeric when in sequential or diverging mode).

colors.updateColorScale(domain) updates the color scale based on the domain array. In general the domain array is an array of data values that the scale should be based on. For a categorical scale, this'll be an array of strings. For numeric (sequential or diverging) scales, this'll be an array of numbers (e.g. [10, 50, 30, 20, 50, 10, 30, 60, 100, 90]).