tessl/npm-shopify--polaris

Shopify's comprehensive admin product component library for React applications with TypeScript support and accessibility features.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Shopify Polaris React Component Library

Name: tessl/npm-shopify--polaris
Author: tessl

Shopify's comprehensive admin product component library for React applications with TypeScript support and accessibility features. Polaris provides a complete design system with 70+ React components, extensive utilities, hooks, and a robust theming system designed specifically for building Shopify merchant admin interfaces.

Package Information

Package Name: @shopify/polaris
Package Type: npm
Language: TypeScript
Installation: npm install @shopify/polaris

Core Imports

import { AppProvider, Button, TextField, Page } from "@shopify/polaris";

For CommonJS:

const { AppProvider, Button, TextField, Page } = require("@shopify/polaris");

Component-specific imports:

import { 
  // Core Application
  AppProvider, Frame, Page, Layout,
  
  // Form Components
  TextField, Button, Checkbox, Select,
  
  // Data Display
  DataTable, IndexTable, ResourceList,
  
  // Navigation
  Navigation, Link, Breadcrumbs,
  
  // Layout & Structure
  Box, BlockStack, InlineStack, Card
} from "@shopify/polaris";

Basic Usage

import React from 'react';
import { AppProvider, Page, Card, Button, TextField } from "@shopify/polaris";

function App() {
  const [value, setValue] = React.useState('');

  // Required i18n configuration
  const i18n = {
    locale: 'en',
    translate: (id: string) => id,
  };

  return (
    <AppProvider i18n={i18n}>
      <Page title="My Store">
        <Card>
          <TextField
            label="Store name"
            value={value}
            onChange={(value) => setValue(value)}
            autoComplete="off"
          />
          <Button variant="primary" onClick={() => console.log('Saved!')}>
            Save
          </Button>
        </Card>
      </Page>
    </AppProvider>
  );
}

export default App;

Architecture

Polaris is built around several key architectural principles:

AppProvider: Root context provider that configures theming, internationalization, and global settings
Component Composition: Components are designed to work together with consistent APIs and shared design tokens
Accessibility First: All components include proper ARIA attributes and keyboard navigation support
Type Safety: Complete TypeScript definitions with strict typing for props and component interfaces
Design System Integration: Components automatically inherit theme values and responsive breakpoints
Enterprise Features: Advanced components for data management, bulk operations, and complex workflows

The library follows a layered architecture:

Foundation Layer: Theme provider, breakpoints, color utilities, and base types
Primitive Layer: Basic UI elements (Button, TextField, Box) with minimal styling
Composite Layer: Complex components (DataTable, Navigation) that combine primitives
Layout Layer: Structure components (Page, Frame, Layout) that organize content
Application Layer: High-level components (AppProvider) that configure the entire system

Capabilities

Core Application Components

Essential components for setting up and structuring Shopify admin applications, including the root provider and main layout containers.

interface AppProviderProps {
  /** Theme name selection */
  theme?: ThemeName;
  /** A locale object or array of locale objects (REQUIRED) */
  i18n: ConstructorParameters<typeof I18n>[0];
  /** A custom component to use for all links */
  linkComponent?: LinkLikeComponent;
  /** For toggling features */
  features?: FeaturesConfig;
  /** Inner content of the application */
  children?: React.ReactNode;
}

interface PageProps extends HeaderProps {
  /** The contents of the page */
  children?: React.ReactNode;
  /** Remove the normal max-width on the page */
  fullWidth?: boolean;
  /** Decreases the maximum layout width */
  narrowWidth?: boolean;
}

Core Application Components

Form Components

Comprehensive form controls with validation, labeling, and accessibility features for building data entry interfaces.

interface TextFieldProps {
  /** Label for the input */
  label: React.ReactNode;
  /** Initial value for the input */
  value?: string;
  /** Callback fired when value is changed */
  onChange?(value: string, id: string): void;
  /** Determine type of input */
  type?: 'text' | 'email' | 'number' | 'integer' | 'password' | 'search' | 'tel' | 'url' | 'date' | 'datetime-local' | 'month' | 'time' | 'week' | 'currency';
  /** Error to display beneath the label */
  error?: Error | boolean;
  /** Additional hint text to display */
  helpText?: React.ReactNode;
  /** Hint text to display */
  placeholder?: string;
  /** Disable the input */
  disabled?: boolean;
  /** Enable automatic completion (REQUIRED) */
  autoComplete: string;
}

interface CheckboxProps {
  label: React.ReactNode;
  checked: boolean | 'indeterminate';
  onChange: (newChecked: boolean) => void;
  disabled?: boolean;
  error?: Error;
  helpText?: React.ReactNode;
}

Form Components

Data Display Components

Advanced components for displaying, sorting, and managing large datasets with selection and bulk operations.

interface DataTableProps {
  columnContentTypes: ColumnContentType[];
  headings: React.ReactNode[];
  rows: TableRow[];
  sortable?: boolean[];
  defaultSortDirection?: SortDirection;
  initialSortColumnIndex?: number;
  onSort?: (headingIndex: number, direction: SortDirection) => void;
}

interface IndexTableProps extends DataTableProps {
  resourceName: { singular: string; plural: string };
  selectedItemsCount: number | 'All';
  onSelectionChange: (selectionType: SelectionType, selection: boolean | string[]) => void;
  bulkActions?: BulkAction[];
}

Data Display Components

Navigation Components

Navigation and linking components for building consistent user flows and site structure.

interface NavigationProps {
  location: string;
  children?: React.ReactNode;
  contextControl?: React.ReactNode;
  onDismiss?: () => void;
}

interface BreadcrumbsProps {
  breadcrumbs: Breadcrumb[];
}

interface PaginationProps {
  hasPrevious?: boolean;
  onPrevious?: () => void;
  hasNext?: boolean;
  onNext?: () => void;
  label: string;
}

Navigation Components

Layout & Structure Utilities

Flexible layout components and utilities for organizing content with consistent spacing and responsive behavior.

interface BoxProps {
  children?: React.ReactNode;
  padding?: SpaceScale;
  paddingInlineStart?: SpaceScale;
  paddingInlineEnd?: SpaceScale;
  paddingBlockStart?: SpaceScale;
  paddingBlockEnd?: SpaceScale;
  background?: ColorBackgroundAlias;
  borderRadius?: BorderRadiusScale;
}

interface BlockStackProps {
  children?: React.ReactNode;
  gap?: SpaceScale;
  align?: 'start' | 'center' | 'end' | 'stretch';
}

Layout & Structure Utilities

Feedback & Overlay Components

Modal dialogs, notifications, and overlay components for user feedback and contextual information.

interface ModalProps {
  open: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
  primaryAction?: PrimaryAction;
  secondaryActions?: SecondaryAction[];
  size?: 'small' | 'medium' | 'large';
}

interface BannerProps {
  title?: string;
  children?: React.ReactNode;
  tone?: BannerTone;
  onDismiss?: () => void;
  action?: Action;
  secondaryAction?: Action;
}

Feedback & Overlay Components

Actions & Button Components

Button variants, action lists, and interactive components for user actions and commands.

interface ButtonProps {
  children?: React.ReactNode;
  onClick?: () => void;
  disabled?: boolean;
  loading?: boolean;
  variant?: 'primary' | 'secondary' | 'plain' | 'monochromePlain';
  tone?: 'default' | 'success' | 'critical';
  size?: 'micro' | 'small' | 'medium' | 'large';
  icon?: IconSource;
}

interface ActionListProps {
  items?: ActionListItemDescriptor[];
  sections?: ActionListSection[];
  actionRole?: string;
  onActionAnyItem?: ActionListItemDescriptor['onAction'];
}

Actions & Button Components

Media & Icon Components

Image handling, icons, avatars, and media display components with responsive loading and accessibility features.

interface IconProps {
  source: IconSource;
  tone?: 'base' | 'disabled' | 'inherit' | 'emphasized' | 'caution' | 'warning' | 'critical' | 'success' | 'info' | 'magic';
  accessibilityLabel?: string;
}

interface AvatarProps {
  size?: 'extraSmall' | 'small' | 'medium' | 'large';
  customer?: boolean;
  name?: string;
  source?: string;
  accessibilityLabel?: string;
}

Media & Icon Components

Utilities & Hooks

React hooks, utility functions, color transformations, and helper methods for enhanced functionality.

// Core Hooks
function useFrame(): FrameContext;
function useTheme(): Theme;
function useBreakpoints(options?: UseBreakpointsOptions): BreakpointsMatches;
function useMediaQuery(query: string): boolean;

// Color Utilities
function rgbToHex(color: RGBColor): string;
function hsbToRgb(color: HSBColor): RGBColor;
function hexToRgb(color: string): RGBColor | null;

// IndexTable Utilities
function useIndexResourceState<T>(resources: T[], options?: IndexResourceStateOptions<T>): IndexResourceState<T>;

Utilities & Hooks

Types & Interfaces

Complete TypeScript type definitions, interfaces, and enums for type-safe development.

// Core Types
type IconSource = React.ComponentType<any> | 'placeholder' | string;
type HeadingTagName = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
type Error = string | React.ReactNode | (string | React.ReactNode)[];

// Action Types
interface Action {
  content?: string;
  accessibilityLabel?: string;
  url?: string;
  external?: boolean;
  onAction?(): void;
  onMouseEnter?(): void;
  onTouchStart?(): void;
}

// Utility Types
type NonEmptyArray<T> = [T, ...T[]];
type ArrayElement<T extends ReadonlyArray<unknown>> = T extends ReadonlyArray<infer ElementType> ? ElementType : never;

Types & Interfaces