Getting Started with Victory

Victory is an opinionated, but fully overridable, ecosystem of composable React components for building interactive data visualizations. The following tutorial explains how to set up a basic chart. For next steps, please see our FAQs and Gallery sections. For more advanced examples, check out our guides.

Check out the native version of this getting started tutorial

In this guide, we’ll show you how to get started with Victory and walk you through the creation and customization of a composed chart. We’ve created a GitHub repository with the completed project, and will link to the corresponding commit where appropriate to help you follow along. If you want, you can view the completed tutorial here.

You can do this on your own if you'd like, or you can...

• Clone down this project we've started for you using git clone git@github.com:FormidableLabs/victory-tutorial.git
• cd victory-tutorial
• Replace the existing code in the client.js file with:

import React from 'react';
import ReactDOM from 'react-dom';

class Main extends React.Component {
  render() {
    return (
      <div>
        <h1>Victory Tutorial</h1>
      </div>
    );
  }
}

const app = document.getElementById('app');
ReactDOM.render(<Main />, app);

• Run npm install to install all necessary dependencies.

Once you've completed these steps, you can run the webpack server with the command npm start, and the project will render at localhost:8080. All modifications will take place in your client.js file.

Add Victory to your project with the command npm install victory, then import it into your React project. For now, let's import the whole library until we know what chart type we'll be using. The imports at the top of your main Javascript file should now look like this:

import React from 'react';
import ReactDOM from 'react-dom';
import * as V from 'victory';

You can import your data from an external file or API, or create an array of data points as a variable. Here is the data that we'll be using for our chart, which is tracking earnings per fiscal quarter:

const data = [
  {quarter: 1, earnings: 13000},
  {quarter: 2, earnings: 16500},
  {quarter: 3, earnings: 14250},
  {quarter: 4, earnings: 19000}
];

Since we're doing a simple comparison of earnings between quarters, let's use a bar chart to visualize the data. We aren't going to need the whole Victory library, so let's change our import statement to reflect only the components that we need.

import React from 'react';
import ReactDOM from 'react-dom';
import { VictoryBar } from 'victory';

Components include sensible defaults, so even without data VictoryBar will render a series of bars with default data.

Let's add some data. VictoryBar looks for x and y values in data points, which our data doesn't have. We can work around this by adding accessor props to our VictoryBar component. (See the commit here.)

VictoryChart is a wrapper component that plots all of its children on the same scale. VictoryChart also provides default axes. Import VictoryChart like so:

import React from 'react';
import ReactDOM from 'react-dom';
import { VictoryBar, VictoryChart } from 'victory';

Next wrap the VictoryBar component in VictoryChart. Default axes are automatically configured to match data provided by VictoryBar. (See the commit here.)

Next, let's modify the tick labels on the axes to be a little more descriptive. We can do this by adding and configuring VictoryAxis components to our chart, so let's import VictoryAxis. Import statements should now look like this:

import React from 'react';
import ReactDOM from 'react-dom';
import { VictoryBar, VictoryChart, VictoryAxis } from 'victory';

In the chart below, we've modified the axes to better fit our needs. If you want to retain a vertical axis, remember to add a second axis component with the dependentAxis prop set to true. We've modified the format of the tick labels on our vertical axis with the tickFormat prop, and have included only the tick values that we need on the horizontal axis by passing an array to the tickValues prop. We've also added the domainPadding prop to our VictoryChart component for good measure, to space the bars further from the y-axis (See the commit here.)

Victory charts come with a default grayscale theme so that all components look clean and consistent. But let’s switch it up with the Victory-provided Material theme. We can do that by importing VictoryTheme and adding a theme prop to VictoryChart. Themes should always be applied to the outermost wrapper component in a chart.

Import statements should look like this:

import React from 'react';
import ReactDOM from 'react-dom';
import { VictoryBar, VictoryChart, VictoryAxis,
        VictoryTheme } from 'victory';

And here's the code and rendered component with the new theme (See the commit here):

Next, let's add more data. In this example we'll compare three years' worth of quarterly earnings in a stacked bar chart. VictoryStack will handle the layout.

import React from 'react';
import ReactDOM from 'react-dom';
import { VictoryBar, VictoryChart, VictoryAxis,
        VictoryTheme, VictoryStack } from 'victory';

Wrap all four VictoryBar components with VictoryStack. (See the commit here.)

VictoryStack can also be used to provide shared styles and props to its children. Let's add a colorScale prop to VictoryStack to override the default colorScale defined in VictoryTheme.material. (See the commit here.)

Congratulations! You’ve created your first chart with Victory. Next, check out our FAQs and Gallery for more examples and information. Happy charting.

For more information about Victory and its components, check out the docs - see VictoryChart to get started. Interested in helping out or seeing what's happening under the hood? Victory is maintained at github.com/FormidableLabs/victory, and you can start contributing here.