visx README

The project's README from github.com/airbnb/visx. As one markdown file: README.md.

visx

visx is a collection of reusable low-level visualization components. visx combines the power of d3 to generate your visualization with the benefits of react for updating the DOM.

[!IMPORTANT] visx v4 is the current stable release and requires React 18 or 19.

npm install @visx/shape

Upgrading from v3? See the visx 4 migration guide.


Docs • Gallery • Changelog • Migration

Usage

Let's make a simple bar graph.

First we'll install the relevant packages:

npm install --save @visx/mock-data @visx/group @visx/shape @visx/scale

import React from 'react';
import { letterFrequency } from '@visx/mock-data';
import { Group } from '@visx/group';
import { Bar } from '@visx/shape';
import { scaleLinear, scaleBand } from '@visx/scale';

// We'll use some mock data from `@visx/mock-data` for this.
const data = letterFrequency;

// Define the graph dimensions and margins
const width = 500;
const height = 500;
const margin = { top: 20, bottom: 20, left: 20, right: 20 };

// Then we'll create some bounds
const xMax = width - margin.left - margin.right;
const yMax = height - margin.top - margin.bottom;

// Accessors
const getLetter = (d) => d.letter;
const getFrequency = (d) => d.frequency * 100;

// And then scale the graph by our data
const xScale = scaleBand({
  range: [0, xMax],
  round: true,
  domain: data.map(getLetter),
  padding: 0.4,
});
const yScale = scaleLinear({
  range: [yMax, 0],
  round: true,
  domain: [0, Math.max(...data.map(getFrequency))],
});

// Finally we'll embed it all in an SVG
function BarGraph() {
  return (
    <svg width={width} height={height}>
      {data.map((d) => {
        const letter = getLetter(d);
        const barHeight = yMax - (yScale(getFrequency(d)) ?? 0);
        return (
          <Group key={`bar-${letter}`}>
            <Bar
              x={xScale(letter)}
              y={yMax - barHeight}
              height={barHeight}
              width={xScale.bandwidth()}
              fill="#fc2e1c"
            />
          </Group>
        );
      })}
    </svg>
  );
}

For more examples using visx, check out the gallery.

Motivation

Goal

The goal is to create a library of components you can use to make both your own reusable chart library or your slick custom one-off chart. visx is largely unopinionated and is meant to be built upon. Keep your bundle sizes down and use only the packages you need.

How?

Under the hood, visx is using d3 for the calculations and math. If you're creating your own awesome chart library on top of visx, it's easy to create a component api that hides d3 entirely. Meaning your team could create charts as easily as using reusable react components.

But why?

Mixing two mental models for updating the DOM is never a good time. Copy and pasting d3 code into useEffect() is just that. This collection of components lets you easily build your own reusable visualization charts or library without having to learn d3. No more selections or enter()/exit()/update().

FAQ

  1. What does visx stand for?

    visx stands for visualization components.

  2. Do you plan on supporting animation/transitions?

    A common criticism of visx is it doesn't have animation baked in, but this was a conscious choice. It's a powerful feature to not bake it in.

    Imagine your app already bundles react-motion, adding a hypothetical @visx/animation is bloat. Since visx is react, it already supports all react animation libs.

    Charting libraries are like style guides. Each org or app will eventually want full control over their own implementation.

    visx makes this easier for everyone. No need to reinvent the wheel each time.

    more info: https://github.com/airbnb/visx/issues/6

  3. Do I have to use every package to make a chart?

    nope! pick and choose the packages you need.

  4. Can I use this to create my own library of charts for my team?

    Please do.

  5. Does visx work with preact?

    yup! alias react + react-dom to preact/compat. For visx v4, configure your package manager to satisfy the React 18/19 peer dependency range.

  6. I like using d3.

    Me too.

Thanks

Thanks to Happo for providing the visual regression testing platform that helps us review UI changes and catch unintended visual regressions.

Happo

Development

Please see CONTRIBUTING.md

:v:

MIT

visx (airbnb/visx)

Searching Database…

21.1K ·GitHub
Visx
Что это такое?visx — это набор переиспользуемых низкоуровневых компонентов для визуализации в React: все вычисления и математика на d3, а рендеринг и обновление DOM берёт на себя React. Вы собираете графики из готовых компонентов вместо того, чтобы писать код выборок d3.
Чем это отличается от обычного d3?Под капотом visx использует d3 для математики, но оборачивает всё в React-компоненты, поэтому не нужно разбираться с выборками и enter()/exit()/update(). Можно даже обернуть это в собственный API компонентов, который полностью скроет d3.
Как добавить его в проект?Установите только нужные вам пакеты @visx — visx разбит на небольшие модули, чтобы размер бандла не разрастался, — и собирайте из них интерфейс в своём React-приложении. В README разобран пример столбчатой диаграммы, а в галерее ещё много примеров.
Какая версия React нужна?visx v4, текущий стабильный релиз, требует React 18 или 19. Работает и Preact, если назначить алиасы react и react-dom на preact/compat и удовлетворить диапазон peer-зависимости React 18/19.
Анимация встроена?Нет — это осознанное решение. visx — обычный React, поэтому он и так работает с любой библиотекой анимации для React; приложение, где уже есть, скажем, react-motion, не будет тянуть дублирующий пакет анимации.
Это готовые графики или конструктор для моей собственной библиотеки диаграмм?И то и другое. Цель — компоненты, из которых можно собрать и свою переиспользуемую библиотеку графиков, и красивый разовый кастомный график. visx почти ничего не навязывает и задуман как основа для надстройки — обернуть его под свою команду прямо поощряется.
Что означает название visx?Это сокращение от visualization components — название буквально повторяет то, чем является библиотека.
Проект ещё активно развивается?Да — текущий стабильный релиз v4 с официальным руководством по миграции с v3 на v4, а в репозитории CI-процессы запускаются на каждый push и pull request.
Он хорошо подходит для проектов на TypeScript?Да — сама кодовая база написана на TypeScript, а пакеты компилируются из исходников .ts и .tsx, так что вы всё время работаете с типизированным кодом.
What are similar projects?victory, G2, recharts, apexcharts.js, blobatar, vue-echarts, d3, vega
Which topics is it in?preact, d3, chart, svg, visualization, monorepo, component-library, data-visualization, ui-components, ui, web-development, react
Creator
airbnb
Size
16.4 MB
Stars
21.1K
Updated
CommitJun 22Releasev4.0.0Jun 11
Age
9y
Commits · 90 Days