@hyperobjekt/scales

This package consists of react components for creating data scales that can be used for data readouts or legends.

It allows for several different types of scales, including:

• ticks
• continuous scales
• category scales
• quantile scales
• quantize scales
• threshold scales
• bubble scales

Each scale consists of a wrapper component with one or more child components.

• <Scale.Colors />: renders the scale's colors
• <Scale.Ticks />: renders an axis to label the scale
• <Scale.Marker /> renders a marker on the scale at a given value
• <Scale.Bubbles /> renders bubbles for the scale config
• <Scale.Chunks />: renders a vertical list of ranges in the scale

Demo

• codesandbox

Usage

Install the package with:

npm i @hyperobjekt/scales

or

yarn add @hyperobjekt/scales

Import the required components and the base CSS styles:

import Scale from "@hyperobjekt/scales";
import "@hyperobjekt/scales/dist/style.css";

Assemble the scale parts as desired:

<Scale type="continuous" min={0} max={100} colors="YlGnBu">
  <Scale.Colors />
  <Scale.Ticks />
  <Scale.Marker value={33} pointer />
</Scale>

Component API

<Scale />

The parent component that contains the scale configuration.

Props

• type: determines which type of scale to use ("category", "continuous", "quantize", "quantile", "threshold", "bubble")
• width: determines the width of the scale
• colors: either an array of colors or a string representing a scale from d3-scale-chromatic
• margin: an object containing top, left, bottom, right margins for the scale
• nice: adjusts the scale to use "nice" values (e.g. 1000 instead of 994) (default: false)
• data: A set of data values to use for the scale
• accessor: A function that selects a data value (used when data is an array of objects instead of an array of values)
• thresholds: Contains threshold points when using threshold scale type
• chunks: Determines how many groups to split data into for quantize and quantile scales.
• min: Minimum value for the scale
• max: Maximum value for the scale
• reverse: whether or not the scale orientation is reversed (max on the left)

<Scale.Colors />

Renders a color scale for the given data and scale type.

Props

• height: height of the color scale

<Scale.Ticks />

Renders tick labels for the given data and scale type.

Props

• ticks: the target number of ticks to show on the scale (continuous)
• tickFormat: a formatter function for ticks on the scale
• tickValues: used to explicitly specify where to render ticks on the scale
• tickSize: size of the ticks on the scale
• tickSizeInner: size of the inner ticks on the scale
• tickSizeOuter: size of the outer ticks on the scale
• tickPadding: padding space between ticks
• endTicks: forces the min and max ticks to show on the scale (overrides ticks props)

<Scale.Marker />

Renders a marker with optional label at a given location on the scale.

Props

• value: determines which point on the scale has the marker
• pointer: when true, renders a pointer on the scale at the value
• renderPointer: a function that takes {color, position, value} and returns JSX to render the pointer
• color: overrides the pointer color (uses value color by default)

<Scale.Bubbles />

Renders bubbles with optional value marker

Props

• minSize: smallest bubble size
• maxSize: largest bubble size
• count: number of bubbles to show (overrides chunks value on parent scale)
• margin: margin for the bubbles scale ({top, bottom, left, right })
• lineLength: sets the line length between the bubble and the label
• formatLabel: function that formats bubble labels
• theme: object containing override properties for styling the bubble, line, and text (e.g. {bubble: {fill:"red", strokeWidth: 5} })
• fillOpacity: sets the fill opacity on bubbles

<Scale.Chunks />

Renders a vertical list of scale chunks with colors and value ranges.

TODO: add ability to hightlight a chunk

Props

• formatLabel: function that takes the chunk value, index, and total chunks and returns a string.

Context

useScaleContext()

You can use the useScaleContext() hook provided by this package to create your own child components. The scale context provides the following:

• width: width of the scale
• margin: margins for the scale
• data: data for the scale
• position: a scale for mapping values to position on the scale
• color: a scale for mapping values to colors
• chunks: objects containing data for "chunks" on discrete scales (not available on continuous scales)
• extent: an array with the [min, max] of the position / color scale
• reverse: whether or not the scale orientation is reversed (max on the left)

Utility Functions

The following utility functions are provided by this package:

getScale(type, {data, accessor, min, max, thresholds, chunks })

Returns all relevant scales for the given type and config object.

getColors(value, numColors)

This function will return an array of hex color strings based on the provided value parameter.

Parameters

• value: either a string containing a scale name from d3-scale-chromatic (e.g. "YlGnBu") or an array of color strings (e.g. ["#f00", "#0f0", "#00f"])
• numColors: the number of colors to return

getColorScale(type, domain, colors)

Returns a color scale that maps a data domain to a color string.

• type: a string representing scale type ("category", "quantile", "quantize", "threshold", "linear", or "sequential")
• domain: the data domain for the scale
• colors: either a string containing a scale name from d3-scale-chromatic (e.g. "YlGnBu") or an array of color strings (e.g. ["#f00", "#0f0", "#00f"]) that will be used to map domain values to

getPositionScale(type, domain, range, options)

Returns a scale that maps a data domain to a pixel value range.

• type: a string representing scale type ("category", "quantile", "threshold", or "linear")
• domain: the data domain for the scale
• range: the range of pixel values to map to
• options: options for the scale
  • nice: when true, the domain is adjusted to have nice values