0
# Shopify Polaris React Component Library
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @shopify/polaris
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @shopify/polaris`
10

11
## Core Imports
12

13
```typescript
14
import { AppProvider, Button, TextField, Page } from "@shopify/polaris";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { AppProvider, Button, TextField, Page } = require("@shopify/polaris");
21
```
22

23
Component-specific imports:
24

25
```typescript
26
import { 
27
  // Core Application
28
  AppProvider, Frame, Page, Layout,
29
  
30
  // Form Components
31
  TextField, Button, Checkbox, Select,
32
  
33
  // Data Display
34
  DataTable, IndexTable, ResourceList,
35
  
36
  // Navigation
37
  Navigation, Link, Breadcrumbs,
38
  
39
  // Layout & Structure
40
  Box, BlockStack, InlineStack, Card
41
} from "@shopify/polaris";
42
```
43

44
## Basic Usage
45

46
```typescript
47
import React from 'react';
48
import { AppProvider, Page, Card, Button, TextField } from "@shopify/polaris";
49

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

53
  // Required i18n configuration
54
  const i18n = {
55
    locale: 'en',
56
    translate: (id: string) => id,
57
  };
58

59
  return (
60
    <AppProvider i18n={i18n}>
61
      <Page title="My Store">
62
        <Card>
63
          <TextField
64
            label="Store name"
65
            value={value}
66
            onChange={(value) => setValue(value)}
67
            autoComplete="off"
68
          />
69
          <Button variant="primary" onClick={() => console.log('Saved!')}>
70
            Save
71
          </Button>
72
        </Card>
73
      </Page>
74
    </AppProvider>
75
  );
76
}
77

78
export default App;
79
```
80

81
## Architecture
82

83
Polaris is built around several key architectural principles:
84

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

92
The library follows a layered architecture:
93
1. **Foundation Layer**: Theme provider, breakpoints, color utilities, and base types
94
2. **Primitive Layer**: Basic UI elements (Button, TextField, Box) with minimal styling
95
3. **Composite Layer**: Complex components (DataTable, Navigation) that combine primitives
96
4. **Layout Layer**: Structure components (Page, Frame, Layout) that organize content
97
5. **Application Layer**: High-level components (AppProvider) that configure the entire system
98

99
## Capabilities
100

101
### Core Application Components
102

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

105
```typescript { .api }
106
interface AppProviderProps {
107
  /** Theme name selection */
108
  theme?: ThemeName;
109
  /** A locale object or array of locale objects (REQUIRED) */
110
  i18n: ConstructorParameters<typeof I18n>[0];
111
  /** A custom component to use for all links */
112
  linkComponent?: LinkLikeComponent;
113
  /** For toggling features */
114
  features?: FeaturesConfig;
115
  /** Inner content of the application */
116
  children?: React.ReactNode;
117
}
118

119
interface PageProps extends HeaderProps {
120
  /** The contents of the page */
121
  children?: React.ReactNode;
122
  /** Remove the normal max-width on the page */
123
  fullWidth?: boolean;
124
  /** Decreases the maximum layout width */
125
  narrowWidth?: boolean;
126
}
127
```
128

129
[Core Application Components](./core-application.md)
130

131
### Form Components
132

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

135
```typescript { .api }
136
interface TextFieldProps {
137
  /** Label for the input */
138
  label: React.ReactNode;
139
  /** Initial value for the input */
140
  value?: string;
141
  /** Callback fired when value is changed */
142
  onChange?(value: string, id: string): void;
143
  /** Determine type of input */
144
  type?: 'text' | 'email' | 'number' | 'integer' | 'password' | 'search' | 'tel' | 'url' | 'date' | 'datetime-local' | 'month' | 'time' | 'week' | 'currency';
145
  /** Error to display beneath the label */
146
  error?: Error | boolean;
147
  /** Additional hint text to display */
148
  helpText?: React.ReactNode;
149
  /** Hint text to display */
150
  placeholder?: string;
151
  /** Disable the input */
152
  disabled?: boolean;
153
  /** Enable automatic completion (REQUIRED) */
154
  autoComplete: string;
155
}
156

157
interface CheckboxProps {
158
  label: React.ReactNode;
159
  checked: boolean | 'indeterminate';
160
  onChange: (newChecked: boolean) => void;
161
  disabled?: boolean;
162
  error?: Error;
163
  helpText?: React.ReactNode;
164
}
165
```
166

167
[Form Components](./form-components.md)
168

169
### Data Display Components
170

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

173
```typescript { .api }
174
interface DataTableProps {
175
  columnContentTypes: ColumnContentType[];
176
  headings: React.ReactNode[];
177
  rows: TableRow[];
178
  sortable?: boolean[];
179
  defaultSortDirection?: SortDirection;
180
  initialSortColumnIndex?: number;
181
  onSort?: (headingIndex: number, direction: SortDirection) => void;
182
}
183

184
interface IndexTableProps extends DataTableProps {
185
  resourceName: { singular: string; plural: string };
186
  selectedItemsCount: number | 'All';
187
  onSelectionChange: (selectionType: SelectionType, selection: boolean | string[]) => void;
188
  bulkActions?: BulkAction[];
189
}
190
```
191

192
[Data Display Components](./data-display.md)
193

194
### Navigation Components
195

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

198
```typescript { .api }
199
interface NavigationProps {
200
  location: string;
201
  children?: React.ReactNode;
202
  contextControl?: React.ReactNode;
203
  onDismiss?: () => void;
204
}
205

206
interface BreadcrumbsProps {
207
  breadcrumbs: Breadcrumb[];
208
}
209

210
interface PaginationProps {
211
  hasPrevious?: boolean;
212
  onPrevious?: () => void;
213
  hasNext?: boolean;
214
  onNext?: () => void;
215
  label: string;
216
}
217
```
218

219
[Navigation Components](./navigation.md)
220

221
### Layout & Structure Utilities
222

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

225
```typescript { .api }
226
interface BoxProps {
227
  children?: React.ReactNode;
228
  padding?: SpaceScale;
229
  paddingInlineStart?: SpaceScale;
230
  paddingInlineEnd?: SpaceScale;
231
  paddingBlockStart?: SpaceScale;
232
  paddingBlockEnd?: SpaceScale;
233
  background?: ColorBackgroundAlias;
234
  borderRadius?: BorderRadiusScale;
235
}
236

237
interface BlockStackProps {
238
  children?: React.ReactNode;
239
  gap?: SpaceScale;
240
  align?: 'start' | 'center' | 'end' | 'stretch';
241
}
242
```
243

244
[Layout & Structure Utilities](./layout-utilities.md)
245

246
### Feedback & Overlay Components
247

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

250
```typescript { .api }
251
interface ModalProps {
252
  open: boolean;
253
  onClose: () => void;
254
  title: string;
255
  children: React.ReactNode;
256
  primaryAction?: PrimaryAction;
257
  secondaryActions?: SecondaryAction[];
258
  size?: 'small' | 'medium' | 'large';
259
}
260

261
interface BannerProps {
262
  title?: string;
263
  children?: React.ReactNode;
264
  tone?: BannerTone;
265
  onDismiss?: () => void;
266
  action?: Action;
267
  secondaryAction?: Action;
268
}
269
```
270

271
[Feedback & Overlay Components](./feedback-overlays.md)
272

273
### Actions & Button Components
274

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

277
```typescript { .api }
278
interface ButtonProps {
279
  children?: React.ReactNode;
280
  onClick?: () => void;
281
  disabled?: boolean;
282
  loading?: boolean;
283
  variant?: 'primary' | 'secondary' | 'plain' | 'monochromePlain';
284
  tone?: 'default' | 'success' | 'critical';
285
  size?: 'micro' | 'small' | 'medium' | 'large';
286
  icon?: IconSource;
287
}
288

289
interface ActionListProps {
290
  items?: ActionListItemDescriptor[];
291
  sections?: ActionListSection[];
292
  actionRole?: string;
293
  onActionAnyItem?: ActionListItemDescriptor['onAction'];
294
}
295
```
296

297
[Actions & Button Components](./actions-buttons.md)
298

299
### Media & Icon Components
300

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

303
```typescript { .api }
304
interface IconProps {
305
  source: IconSource;
306
  tone?: 'base' | 'disabled' | 'inherit' | 'emphasized' | 'caution' | 'warning' | 'critical' | 'success' | 'info' | 'magic';
307
  accessibilityLabel?: string;
308
}
309

310
interface AvatarProps {
311
  size?: 'extraSmall' | 'small' | 'medium' | 'large';
312
  customer?: boolean;
313
  name?: string;
314
  source?: string;
315
  accessibilityLabel?: string;
316
}
317
```
318

319
[Media & Icon Components](./media-icons.md)
320

321
### Utilities & Hooks
322

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

325
```typescript { .api }
326
// Core Hooks
327
function useFrame(): FrameContext;
328
function useTheme(): Theme;
329
function useBreakpoints(options?: UseBreakpointsOptions): BreakpointsMatches;
330
function useMediaQuery(query: string): boolean;
331

332
// Color Utilities
333
function rgbToHex(color: RGBColor): string;
334
function hsbToRgb(color: HSBColor): RGBColor;
335
function hexToRgb(color: string): RGBColor | null;
336

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

341
[Utilities & Hooks](./utilities-hooks.md)
342

343
### Types & Interfaces
344

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

347
```typescript { .api }
348
// Core Types
349
type IconSource = React.ComponentType<any> | 'placeholder' | string;
350
type HeadingTagName = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
351
type Error = string | React.ReactNode | (string | React.ReactNode)[];
352

353
// Action Types
354
interface Action {
355
  content?: string;
356
  accessibilityLabel?: string;
357
  url?: string;
358
  external?: boolean;
359
  onAction?(): void;
360
  onMouseEnter?(): void;
361
  onTouchStart?(): void;
362
}
363

364
// Utility Types
365
type NonEmptyArray<T> = [T, ...T[]];
366
type ArrayElement<T extends ReadonlyArray<unknown>> = T extends ReadonlyArray<infer ElementType> ? ElementType : never;
367
```
368

369
[Types & Interfaces](./types-interfaces.md)