shopify-polaris-viz（Shopify polaris VIZ 命令行）

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

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

Available Chart Components

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

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

Common Props

Most chart components accept these props:

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

External Resources

• GitHub Repository (archived)
• Storybook Documentation
• Polaris Data Visualization Guidelines