Shopify Polaris Viz

Polaris Viz is Shopify's data visualization component library for React. It provides accessible, themeable chart components that match the Shopify Admin visual style.

Note: This library was archived in June 2025. While still functional, Shopify recommends reaching out to support for migration assistance if building new features.

Installation

npm install @shopify/polaris-viz
# Required peer dependencies
npm install @shopify/polaris @shopify/polaris-tokens

Setup

Wrap your application with PolarisVizProvider:

import { PolarisVizProvider } from '@shopify/polaris-viz';
import '@shopify/polaris-viz/build/esm/styles.css';

function App() {
  return (
    <PolarisVizProvider>
      {/* Your app */}
    </PolarisVizProvider>
  );
}

Core Design Principles

One Question Per Chart: Each visualization should answer a single, specific question
Accuracy First: Faithfully represent the original dataset
Accessibility: Support screen readers, color-blind users, and multiple data formats
Consistency: Use Polaris themes for visual harmony with Shopify Admin

Available Chart Components

Component	Use Case	Max Data Points
`BarChart`	Comparing discrete categories	~6 categories
`SimpleBarChart`	Simple horizontal bars	~6 categories
`LineChart`	Trends over time	30+ points
`SparkLineChart`	Compact inline trends	Any
`DonutChart`	Part-to-whole relationships	~6 segments
`StackedAreaChart`	Cumulative trends	30+ points
`FunnelChart`	Conversion funnels	~6 stages

Quick Examples

Bar Chart

import { BarChart } from '@shopify/polaris-viz';

const data = [
  {
    name: 'Sales',
    data: [
      { key: 'Monday', value: 150 },
      { key: 'Tuesday', value: 200 },
      { key: 'Wednesday', value: 175 },
    ],
  },
];

<BarChart data={data} />

Line Chart

import { LineChart } from '@shopify/polaris-viz';

const data = [
  {
    name: 'Orders',
    data: [
      { key: 'Jan', value: 100 },
      { key: 'Feb', value: 150 },
      { key: 'Mar', value: 200 },
    ],
  },
];

<LineChart data={data} />

Donut Chart

import { DonutChart } from '@shopify/polaris-viz';

const data = [
  { name: 'Direct', data: [{ key: 'Direct', value: 200 }] },
  { name: 'Social', data: [{ key: 'Social', value: 150 }] },
  { name: 'Email', data: [{ key: 'Email', value: 100 }] },
];

<DonutChart data={data} />

Spark Line (Inline Trend)

import { SparkLineChart } from '@shopify/polaris-viz';

const data = [
  {
    data: [
      { key: 0, value: 100 },
      { key: 1, value: 150 },
      { key: 2, value: 120 },
      { key: 3, value: 180 },
    ],
  },
];

<SparkLineChart data={data} />

Data Structure

All charts use a consistent DataSeries format:

interface DataPoint {
  key: string | number;  // X-axis value or category
  value: number | null;  // Y-axis value (null for gaps)
}

interface DataSeries {
  name: string;           // Series label
  data: DataPoint[];      // Array of data points
  color?: string;         // Optional color override
  isComparison?: boolean; // Mark as comparison data (renders grey)
}

Theming

Use the theme prop to switch between themes:

// Use built-in themes
<BarChart data={data} theme="Light" />
<BarChart data={data} theme="Dark" />

// Or define custom themes in provider
<PolarisVizProvider
  themes={{
    MyBrand: {
      chartContainer: { backgroundColor: '#f9f9f9' },
      seriesColors: { upToEight: ['#5c6ac4', '#47c1bf'] },
    },
  }}
>
  <BarChart data={data} theme="MyBrand" />
</PolarisVizProvider>

Color Guidelines

Single series: Use one consistent color
Comparison to past: Current = purple, Historical = grey
Multiple series: Use contrasting colors (max 4 lines recommended)
Positive/Negative: Green = positive, Red = negative

Accessibility Requirements

Color contrast: Ensure sufficient contrast between elements
Screen readers: Charts render with ARIA attributes
Text alternatives: Provide data tables as alternative format
No color-only meaning: Use patterns or labels alongside color

Common Props

Most chart components accept these props:

Prop	Type	Description
`data`	`DataSeries[]`	Chart data
`theme`	`string`	Theme name
`isAnimated`	`boolean`	Enable/disable animations
`showLegend`	`boolean`	Show legend
`xAxisOptions`	`object`	X-axis configuration
`yAxisOptions`	`object`	Y-axis configuration
`emptyStateText`	`string`	Text when no data

Axis Label Formatting

Follow Shopify's formatting standards:

Times: 12-hour lowercase (12am, 6pm)
Days: Three letters (Sun, Mon)
Months: Three letters (Feb, Mar)
Dates: "10 Apr" format
Numbers: Use "k" for thousands, max 3 digits + decimal + letter

Anti-Patterns to Avoid

DO NOT exceed 6 categories in bar/donut charts - use tables instead
DO NOT use more than 4 lines in a line chart
DO NOT rely on color alone to convey meaning
DO NOT use edge-to-edge axis lines - keep them within data range
DO NOT mix Polaris Viz with other chart libraries in the same app

References

Chart Components - Detailed props and examples for each chart type
Theming Guide - Custom theme configuration
Data Structures - Complete TypeScript interfaces

shopify-polaris-viz