Polaris Viz

Polaris Viz is Shopify's data visualization system designed to prioritize accessibility and motion design for clear analytics experiences. It is split into two primary consumer-facing libraries:

• @shopify/polaris-viz: A collection of React components built for web environments.
• @shopify/polaris-viz-native: A collection of React Native components optimized for mobile experiences.

Both libraries share a common foundation, including:

• Data Structure: The format used to feed data into charts.
• Utility functions: Shared logic for accessibility, color vision, and events.
• Themes: Shared visual styling and default themes.
• SubComponents: Shared building blocks for chart construction.

All shared logic and components are documented in the Shared folder of the Polaris Viz Storybook.

Polaris Viz provides a collection of data visualization components for both Web (React) and Mobile (React Native) environments. You can browse the available chart types through the Storybook documentation, which categorizes them into:

• Web Components: React-based charts designed for web applications.
• Mobile Components: React Native-based charts designed for mobile applications.

The repository is organized into several key areas:

• /packages: Contains the source code for published libraries:
  • packages/polaris-viz $\rightarrow$ @shopify/polaris-viz
  • packages/polaris-viz-native $\rightarrow$ @shopify/polaris-viz-native
  • packages/polaris-viz-core $\rightarrow$ @shopify/polaris-viz-core (contains platform-agnostic code shared by both web and native libraries).
• */**/stories/: Storybook files used for component documentation and development. These are located in /src/ folders within each package.
• /sandbox: An Expo app for testing library builds across web, iOS, and Android platforms.

Shopify provides three distinct analytics experiences tailored to different merchant needs:

1. In-context analytics experiences: Surface relevant metrics directly within operational admin spaces (like Orders, Products, or Customers) to support day-to-day decision-making.
2. Report experiences: Provide a comprehensive view of a dataset, typically combining a data visualization (chart) and a data table. Reports allow for minor modifications like adding filters, but significant changes require editing the underlying query in a Notebook.
3. Notebook experiences: An exploratory tool for deep data analysis. Notebooks allow merchants to create new ShopifyQL queries from scratch or modify existing queries used in Shopify-generated reports.

The line chart is designed for discrete data where data points are collected over uniform, equally spaced time intervals (e.g., one data point per hour).

Best use cases:

• Showing discrete data like sales or orders over regular intervals.
• Visualizing how data trends or changes over time.

Data tables present information in a structured tabular form using rows and columns.

Best use cases:

• Detailed data displays often found in notebooks and reports (e.g., a list of specific orders with multiple attributes).

Vertical bar charts are used to present categorical data—data that can be organized into groups.

Best use cases:

• Communicating discrete values for specific groupings (e.g., total orders per product, sales by geographical location, or sales by channel).
• Representing categories like age, education level, or language.

You can define multiple custom themes by adding extra keys to the themes object in PolarisVizProvider. Each key acts as a unique theme name. To use a specific theme on a chart, pass the corresponding name to the chart's theme prop.

<PolarisVizProvider
  themes={{
    AngryRed: {
      seriesColors: {
        single: ['black'],
      },
      chartContainer: {
        backgroundColor: '#ff0025',
      },
    },
    HappyGreen: {
      seriesColors: {
        single: ['black'],
      },
      chartContainer: {
        backgroundColor: '#00ff64',
      },
    },
  }}
>
  <SparkLineChart series={...} theme='AngryRed'/>
  <SparkLineChart series={...} theme='HappyGreen'/>
</PolarisVizProvider>