shopify-polaris-viz

Original：🇺🇸 English

Translated

Guide for creating data visualizations in Shopify Apps using the Polaris Viz library. Use this skill when building charts, graphs, dashboards, or any data visualization components that need to integrate with the Shopify Admin aesthetic. Covers BarChart, LineChart, DonutChart, SparkLineChart, and theming.

2installs

Sourcetoilahuongg/shopify-agents-kit

Added on2026-03-04

NPX Install

npx skill4agent add toilahuongg/shopify-agents-kit shopify-polaris-viz

SKILL.md Content

View Translation Comparison →

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

bash

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

Setup

Wrap your application with

PolarisVizProvider

:

jsx

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

jsx

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

jsx

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

jsx

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)

jsx

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:

typescript

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:

jsx

// 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