Установка и первый запуск

Nivo — библиотека визуализации данных, построенная на основе React-экосистемы и ориентированная на создание сложных интерактивных графиков без необходимости напрямую работать с низкоуровневыми примитивами SVG и Canvas. В основе архитектуры лежит модульный подход: каждый тип графика поставляется как отдельный пакет, что позволяет подключать только необходимый функционал и снижать итоговый размер сборки.

Библиотека распространяется как набор scoped-пакетов npm, начинающихся с @nivo/. Такой подход обеспечивает независимость графиков друг от друга и упрощает управление зависимостями в проектах.

Ключевые пакеты:

  • @nivo/core — базовые утилиты и общие компоненты
  • @nivo/bar — столбчатые диаграммы
  • @nivo/line — линейные графики
  • @nivo/pie — круговые диаграммы
  • @nivo/scatterplot — диаграммы рассеяния
  • @nivo/geo — географические карты

Основная зависимость — React. Библиотека не предназначена для использования вне React-окружения.

Установка через npm

npm install @nivo/core @nivo/bar

При установке часто подключается только нужный пакет визуализации. Например, для линейных графиков:

npm install @nivo/core @nivo/line

Установка через yarn

yarn add @nivo/core @nivo/bar

Установка через pnpm

pnpm add @nivo/core @nivo/bar

Подключение React-зависимости

Если проект не содержит React, необходимо установить его явно:

npm install react react-dom

Современные сборщики (Vite, Next.js, CRA) уже включают базовую конфигурацию React, поэтому дополнительная настройка обычно не требуется.

Структура проекта для первого запуска

Типовая структура React-приложения с Nivo:

src/
 ├── components/
 │    └── BarChart.jsx
 ├── data/
 │    └── salesData.js
 ├── App.jsx
 └── main.jsx

Данные для графика выносятся отдельно, чтобы обеспечить переиспользование компонентов визуализации.

Пример набора данных

export const salesData = [
  {
    country: "USA",
    "2023": 120,
    "2024": 150
  },
  {
    country: "Germany",
    "2023": 98,
    "2024": 110
  },
  {
    country: "Japan",
    "2023": 86,
    "2024": 95
  }
];

Первый компонент с графиком

Наиболее распространённый стартовый элемент — столбчатая диаграмма (Bar). Она хорошо демонстрирует базовую модель работы Nivo: данные → маппинг → рендеринг.

Импорт компонента

import { ResponsiveBar } from "@nivo/bar";

Минимальная реализация BarChart

import React from "react";
import { ResponsiveBar } from "@nivo/bar";
import { salesData } from "../data/salesData";

const BarChart = () => {
  return (
    <div style={{ height: 400 }}>
      <ResponsiveBar
        data={salesData}
        keys={["2023", "2024"]}
        indexBy="country"
        margin={{ top: 50, right: 50, bottom: 50, left: 60 }}
        padding={0.3}
        colors={{ scheme: "nivo" }}
        axisBottom={{
          tickSize: 5,
          tickPadding: 5,
          tickRotation: 0,
          legend: "Страны",
          legendPosition: "middle",
          legendOffset: 40
        }}
        axisLeft={{
          tickSize: 5,
          tickPadding: 5,
          tickRotation: 0,
          legend: "Продажи",
          legendPosition: "middle",
          legendOffset: -50
        }}
      />
    </div>
  );
};

export default BarChart;

Встраивание в приложение

Компонент графика подключается на уровне корневого приложения.

App.jsx

import React from "react";
import BarChart from "./components/BarChart";

const App = () => {
  return (
    <div>
      <h1>Аналитика продаж</h1>
      <BarChart />
    </div>
  );
};

export default App;

main.jsx (Vite)

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Responsive-подход и контейнерная модель

Одной из ключевых особенностей Nivo является использование responsive-компонентов. Они автоматически подстраиваются под размеры родительского контейнера.

Важно учитывать:

  • родительский блок обязан иметь заданную высоту
  • ширина обычно вычисляется автоматически
  • отсутствие высоты приводит к нулевому рендеру

Пример критического требования:

<div style={{ height: 500 }}>
  <ResponsiveBar {...props} />
</div>

Базовые параметры конфигурации

data

Массив объектов, содержащих измерения и значения. Структура должна быть согласована с keys и indexBy.

keys

Определяет поля значений, которые будут визуализированы.

keys={["2023", "2024"]}

indexBy

Определяет категориальную ось:

indexBy="country"

Цветовые схемы

Nivo предоставляет встроенные палитры:

  • nivo
  • category10
  • accent
  • paired

Пример:

colors={{ scheme: "accent" }}

Цветовая система основана на предопределённых наборах D3-подобных палитр и может быть расширена кастомными функциями.

Поведение при первом рендере

При первом запуске компонента происходит:

  1. Инициализация SVG-контейнера
  2. Вычисление размеров контейнера
  3. Построение шкал (scales)
  4. Маппинг данных на координаты
  5. Рендер осей и сетки
  6. Отрисовка баров с анимацией появления

Анимации включены по умолчанию и управляются через motion параметры.

Отключение анимации

animate={false}

или

motionConfig="wobbly"

(конфигурации motion основаны на react-spring)

Частые проблемы первого запуска

График не отображается

Основная причина — отсутствие высоты у контейнера.

Ошибка “Responsive component rendered outside container”

Возникает при рендере без корректного layout-обёртывания.

Пустые данные

Если data пустой массив, Nivo отрисовывает оси без значений.

Подключение нескольких графиков

Библиотека допускает одновременное использование разных типов визуализации.

npm install @nivo/line @nivo/pie

Каждый график работает независимо, что позволяет комбинировать визуализации в одном интерфейсе без конфликтов состояния.

Режим отладки

При разработке полезно включать упрощённые настройки:

  • фиксированная высота контейнера
  • отключённые анимации
  • минимальный набор props

Это ускоряет итерации и упрощает диагностику поведения рендера.

Оглавление