@vx/scale

What is @vx/scale?

@vx/scale is a part of the vx (now known as visx) collection of visualization components for React. It provides a set of utilities for creating scales, which are functions that map from an input domain to an output range. These scales are essential for creating visualizations as they help in mapping data values to visual properties like position, color, and size.

What are @vx/scale's main functionalities?

Linear Scale

Linear scales map a continuous input domain to a continuous output range. This is useful for creating visualizations where you need a direct proportional mapping, such as bar charts or scatter plots.

const scaleLinear = require('@vx/scale').scaleLinear;
const linear = scaleLinear({
  domain: [0, 100],
  range: [0, 500]
});
console.log(linear(50)); // 250

Band Scale

Band scales are useful for creating visualizations with discrete bands, such as bar charts with categorical data. They map a discrete domain to a continuous range with optional padding between bands.

const scaleBand = require('@vx/scale').scaleBand;
const band = scaleBand({
  domain: ['A', 'B', 'C'],
  range: [0, 300],
  padding: 0.1
});
console.log(band('B')); // 110

Ordinal Scale

Ordinal scales map a discrete domain to a discrete range. This is useful for mapping categories to colors or other visual properties.

const scaleOrdinal = require('@vx/scale').scaleOrdinal;
const ordinal = scaleOrdinal({
  domain: ['apple', 'banana', 'cherry'],
  range: ['red', 'yellow', 'purple']
});
console.log(ordinal('banana')); // 'yellow'

Time Scale

Time scales are used for mapping dates and times to a continuous range. This is particularly useful for time series data.

const scaleTime = require('@vx/scale').scaleTime;
const time = scaleTime({
  domain: [new Date(2020, 0, 1), new Date(2020, 11, 31)],
  range: [0, 100]
});
console.log(time(new Date(2020, 5, 1))); // 50

Other packages similar to @vx/scale

d3-scale

d3-scale is a part of the D3.js library and provides similar functionality for creating scales. It is highly flexible and widely used in the data visualization community. Compared to @vx/scale, d3-scale is more mature and has a larger user base, but @vx/scale is designed to integrate more seamlessly with React applications.

victory

Victory is a collection of composable React components for building interactive data visualizations. It includes its own set of scale utilities similar to @vx/scale. Victory is more opinionated and provides higher-level components, making it easier to get started with, but potentially less flexible than @vx/scale for custom visualizations.

recharts

Recharts is another library for building charts with React. It provides built-in scales and is designed to be easy to use with a focus on simplicity and performance. While it offers less flexibility compared to @vx/scale, it is a good choice for quickly building standard chart types.

README

@vx/scale

npm install --save @vx/scale

Overview of Scaling

The @vx/scale package aims to provide a wrapper around existing d3 scaling originally defined in the d3-scale package.

Scales are functions that help you map your data to the physical pixel size that your graph requires. For example, let's say you wanted to create a bar chart to show populations per country. If you were to use a 1-to-1 scale (IE: 1 pixel per y value) your bar for the USA would be about 321.4 million pixels high!

Instead, you can tell vx a function to use that takes a value (like your population per country) and spits out another value.

For example, we could create a linear scale like this:

const graphHeight = 500; // We'll have a 500 pixel high graph
const maxPopulation = getMostPopulatedCountryInTheWorld();

const yScale = Scale.scaleLinear({
  rangeRound: [graphHeight, 0],
  domain: [0, maxPopulation],
});

// ...

const bars = data.map((d, i) => {
  const barHeight = graphHeight - yScale(d.y);
  return <Shape.Bar height={barHeight} y={graphHeight - barHeight} />
})

Note: This example represents how to use a yScale, but skipped a lot of details about how to make a bar chart. If you're trying to do that, you should check out this example.

Current Scaling Options

Band Scaling

Original d3 docs

Example:

const scale = Scale.scaleBand({
  /*
    range,
    rangeRound,
    domain,
    padding,
    nice = false
  */
});

Linear Scaling

Original d3 docs

Example:

const scale = Scale.scaleLinear({
  /*
    range,
    rangeRound,
    domain,
    nice = false,
    clamp = false,
  */
});

Log Scaling

Original d3 docs

Example:

const scale = Scale.scaleLog({
  /*
    range,
    rangeRound,
    domain,
    base,
    nice = false,
    clamp = false,
  */
});

Ordinal Scaling

Original d3 docs

Example:

const scale = Scale.scaleOrdinal({
  /*
    range,
    domain,
    unknown,
  */
});

Point Scaling

Original d3 docs

Example:

const scale = Scale.scalePoint({
  /*
    range,
    rangeRound,
    domain,
    padding,
    align,
    nice = false,
  */
});

Power Scaling

Original d3 docs

Example:

const scale = Scale.scalePower({
  /*
    range,
    rangeRound,
    domain,
    exponent,
    nice = false,
    clamp = false,
  */
});

Square Root Scaling

Original d3 docs

Example:

// No need to set the exponent, It is always 0.5
const scale = Scale.scaleSqrt({
  /*
    range,
    rangeRound,
    domain,
    nice = false,
    clamp = false,
  */
});

Time Scaling

Original d3 docs

Example:

const scale = Scale.scaleTime({
  /*
    range,
    rangeRound,
    domain,
    nice = false,
    clamp = false,
   */
});

You also can scale time with Coordinated Universal Time via scaleUtc.

Example:

const scale = Scale.scaleUtc({
  /*
    range,
    rangeRound,
    domain,
    nice = false,
    clamp = false,
   */
});

Color Scales

D3 scales offer the ability to map points to colors. You can use d3-scale-chromatic in conjunction with vx's scaleOrdinal to make color scales.

You can install d3-scale-chromatic with npm:

npm install --save d3-scale-chromatic

You create a color scale like so:

import { scaleOrdinal } from '@vx/scale';
import { schemeSet1 } from 'd3-scale-chromatic';

const colorScale = scaleOrdinal({
  domain: arrayOfThings,
  range: schemeSet1
});

This generates a color scale with the following colors:

There are a number of other categorical color schemes available, along with other continuous color schemes.

Changelog

v0.0.194

:trophy: Contributors

• ptmx
• dennisja
• gillesdemey
• mitchellwarr
• williaster

:rocket: Enhancements

• [brush] Add resetOnEnd prop #614
• [tooltip] Add hook for custom Tooltip container to support SVG tooltips #610
• [scale] Add sqrtScale #615

:bug: Bug Fix

• [zoom] Don't use stale zoom constraint prop #578
• [responsive] Don't render withParentSize base component until size is known #621

Changes:
 - @vx/annotation: 0.0.193 => 0.0.194
 - @vx/axis: 0.0.193 => 0.0.194
 - @vx/bounds: 0.0.193 => 0.0.194
 - @vx/brush: 0.0.193 => 0.0.194
 - @vx/chord: 0.0.193 => 0.0.194
 - @vx/clip-path: 0.0.193 => 0.0.194
 - @vx/curve: 0.0.193 => 0.0.194
 - @vx/demo: 0.0.193 => 0.0.194
 - @vx/drag: 0.0.193 => 0.0.194
 - @vx/event: 0.0.193 => 0.0.194
 - @vx/geo: 0.0.193 => 0.0.194
 - @vx/glyph: 0.0.193 => 0.0.194
 - @vx/gradient: 0.0.193 => 0.0.194
 - @vx/grid: 0.0.193 => 0.0.194
 - @vx/group: 0.0.193 => 0.0.194
 - @vx/heatmap: 0.0.193 => 0.0.194
 - @vx/hierarchy: 0.0.193 => 0.0.194
 - @vx/legend: 0.0.193 => 0.0.194
 - @vx/marker: 0.0.193 => 0.0.194
 - @vx/mock-data: 0.0.193 => 0.0.194
 - @vx/network: 0.0.193 => 0.0.194
 - @vx/pattern: 0.0.193 => 0.0.194
 - @vx/point: 0.0.193 => 0.0.194
 - @vx/responsive: 0.0.193 => 0.0.194
 - @vx/scale: 0.0.193 => 0.0.194
 - @vx/shape: 0.0.193 => 0.0.194
 - @vx/stats: 0.0.193 => 0.0.194
 - @vx/text: 0.0.193 => 0.0.194
 - @vx/threshold: 0.0.193 => 0.0.194
 - @vx/tooltip: 0.0.193 => 0.0.194
 - @vx/voronoi: 0.0.193 => 0.0.194
 - @vx/vx: 0.0.193 => 0.0.194
 - @vx/zoom: 0.0.193 => 0.0.194