The visx Guide: From Your Data to a Working React Chart

Everything you need to use visx.app and visx itself: previewing data, downloading and installing the code, customizing charts, fixing common problems and following good habits.

1. visx in one minute

visx is an open-source set of React packages, created at Airbnb, for building charts. It combines D3’s calculations (scales, shapes, layouts) with React rendering. Instead of one big <Chart> component with dozens of options, you get small building blocks: a scale package, a shape package, an axis package and so on. You assemble them into exactly the chart you need.

That flexibility is the reason to choose visx, and also the reason the first chart takes effort. This guide, the playground and the starter kit exist to remove that first-chart friction.

2. Using the chart playground

The playground on the homepage lets you test any dataset without installing anything.

  1. Enter data. Choose an example from the dropdown or type your own rows in the format label, value, one per line. Colons, semicolons and tabs work as separators too, so you can paste two columns straight from a spreadsheet.
  2. Check the message line. Up to 24 rows are used. Labels are trimmed to 16 characters and negative values are skipped. Any skipped row is listed under the text box so nothing disappears silently.
  3. Compare chart types. Nine chart cards are shown first. Click Show 3 more charts for the radar chart, heat strip and sparkline. Click Preview on a card to load it into the large preview.
  4. Style it. Pick a colour theme, toggle grid lines and value labels, or sort values from high to low. Hover the large preview to see exact values.
  5. Copy the usage code. The code box under the preview shows how to render the matching component with your current data and colour.

Everything in the playground runs in your browser. Your data is never sent to our server.

3. Downloading files

The downloads page offers three kinds of file:

DownloadFormatUse it when
Starter kitZIP of a Vite + React + TypeScript projectYou’re starting fresh or want to explore every chart
Single component.tsx fileYou already have a React app and need one chart
Sample dataCSV or JSONYou want to see the expected data shape
Chart imageSVG or PNG (from the playground)You need a picture for a document, slide or post

Single components import two small shared files, types.ts and theme.ts. They’re in the starter kit’s src/charts folder, so the simplest route is usually to download the ZIP and copy the files you need.

4. Installing and running the starter kit

You’ll need Node.js 20.19+ or 22.12+ (required by Vite 8) and a terminal.

# 1. unzip, then move into the folder
cd visx-react-starter

# 2. install dependencies from the npm registry
npm install

# 3. start the development server
npm run dev

Open the address Vite prints, usually http://localhost:5173. You’ll see all twelve charts drawn from data/sample-data.json. Edit that file and the page refreshes automatically. To create a production build, run npm run build. It type-checks the project first, then writes optimized files to dist/.

Prefer Yarn or pnpm? yarn / pnpm install followed by yarn dev / pnpm dev work the same way.

5. Using a chart in your own app

Every component takes the same props, which makes swapping chart types a one-word change:

import { ParentSize } from '@visx/responsive';
import { BarChart } from './charts';

const data = [
  { label: 'Jan', value: 42 },
  { label: 'Feb', value: 58 },
];

export function SalesChart() {
  return (
    <div style={{ height: 320 }}>
      <ParentSize>
        {({ width }) => <BarChart data={data} width={width} height={320} color="#4f46e5" />}
      </ParentSize>
    </div>
  );
}

Install the @visx packages the component imports (listed at the top of each file), plus @visx/responsive for ParentSize. Keep every visx package on the same major version.

6. Customizing charts

  • Colours: pass color, or edit palette in theme.ts to change every chart at once, including multi-colour pies.
  • Spacing: pass a margin prop. Increase left when y-axis labels are long.
  • Axis labels: change tickLabel in theme.ts, or add tickFormat to an axis to show currency or percentages.
  • Curves: swap curveMonotoneX for curveLinear, curveStep or any other factory from @visx/curve.
  • Interactivity: copy the tooltip pattern from BarChart.tsx (useTooltip, localPoint, TooltipWithBounds) into any other chart.

7. Troubleshooting

The chart is blank or cut off

In visx 4, ParentSize fills its parent and draws inside an absolutely positioned box. Give the parent an explicit height, as in the example above. This is the most common issue we see.

"Cannot find module '@visx/…'"

Install that specific package. Also check you aren’t using a deep import such as @visx/shape/lib/..., which visx 4 no longer supports.

TypeScript errors after upgrading

Run npm ls | grep @visx. If you see a mix of 3.x and 4.x, upgrade all of them together.

npm install fails

Check node -v. Older Node releases can’t run Vite 8. Corporate networks sometimes need a registry or proxy setting from your IT team.

The ZIP won’t open

Re-download it. If the problem persists, try a different unzip tool, then let us know.

More fixes are in the full visx troubleshooting checklist.

8. Best practices

  • Pick the chart for the question. Use bars to compare categories, lines for change over time and pies only for a few parts of a whole.
  • Start the value axis at zero for bars. Truncated bar axes exaggerate differences.
  • Label clearly. Add units to axis labels or the title, and don’t rely on colour alone to tell series apart.
  • Make charts accessible. Keep role="img" and a descriptive aria-label on each SVG, and offer the data as a table nearby for screen-reader users.
  • Memoise scales. Wrap scale creation in useMemo keyed on data and size when charts re-render often.
  • Keep data volumes sensible. SVG is ideal for hundreds of marks. Aggregate before charting tens of thousands.
  • Pin versions. Commit your lockfile and upgrade all @visx packages together.

9. Quick answers

Do I need to know D3?

No. Understanding what a scale does helps, and our beginner article explains it in a few minutes.

Can I use the components without TypeScript?

Yes. Rename the file to .jsx and delete the type annotations, or keep TypeScript, which Vite and Next.js support out of the box.

Can I use these charts in a commercial project?

Yes. Both visx and our components are MIT licensed. See visx license and safety.

Does it work with Next.js?

Yes. Put chart components in a file marked 'use client' when using the App Router. Details are in visx compatibility.