Victory
Victory

About Docs Gallery Support GitHub FAQs

#
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.

####
Getting Started with Victory Native?

Check out the native version of this getting started tutorial

##
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.

####
1. Set up a basic React project

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.

####
2. Add Victory

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';

####
3. Add your data

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}
    ];

####
4. Add your first Victory component

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.)

####
5. Add a Chart wrapper

`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.)

####
6. Customize the axes

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.)

####
7. Add a theme

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):

####
8. Stack multiple bar charts

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.)

####
9. Override theme's color scale

`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.)

##
Next Steps

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

##
Documentation, Contributing, and Source

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.