0
# Core Application Components
1

2
Essential components for setting up and structuring Shopify admin applications. These components provide the foundation layer including the root provider, main layout containers, and application frame structure.
3

4
## Capabilities
5

6
### AppProvider
7

8
Root context provider that configures theming, internationalization, features, and global settings for the entire Polaris application.
9

10
```typescript { .api }
11
/**
12
 * Root provider component that wraps the entire Polaris application
13
 * @param theme - Theme name configuration ('light', 'dark', etc.)
14
 * @param i18n - Internationalization configuration (REQUIRED)
15
 * @param linkComponent - Custom component for all links
16
 * @param features - Feature flags and experimental features
17
 * @param children - Inner content of the application
18
 * @returns JSX element wrapping children with Polaris context
19
 */
20
function AppProvider(props: AppProviderProps): JSX.Element;
21

22
interface AppProviderProps {
23
  /** Theme name selection */
24
  theme?: ThemeName;
25
  /** A locale object or array of locale objects that overrides default translations. If specifying an array then your primary language dictionary should come first, followed by your fallback language dictionaries */
26
  i18n: ConstructorParameters<typeof I18n>[0];
27
  /** A custom component to use for all links used by Polaris components */
28
  linkComponent?: LinkLikeComponent;
29
  /** For toggling features */
30
  features?: FeaturesConfig;
31
  /** Inner content of the application */
32
  children?: React.ReactNode;
33
}
34

35
type ThemeName = 'light' | 'dark' | 'light-mobile' | 'light-high-contrast' | string;
36

37
type LinkLikeComponent = React.ComponentType<{
38
  children?: React.ReactNode;
39
  url: string;
40
  external?: boolean;
41
  [key: string]: any;
42
}>;
43
```
44

45
**Usage Example:**
46

47
```typescript
48
import React from 'react';
49
import { AppProvider, Page } from '@shopify/polaris';
50

51
function App() {
52
  // i18n configuration - REQUIRED parameter
53
  const i18n = {
54
    locale: 'en',
55
    translate: (id: string, options?: any) => id,
56
  };
57

58
  return (
59
    <AppProvider theme="light" i18n={i18n}>
60
      <Page title="My Application">
61
        {/* Your app content */}
62
      </Page>
63
    </AppProvider>
64
  );
65
}
66
```
67

68
### Frame
69

70
Main application frame component that provides the structural layout for Shopify admin applications including navigation, top bar, and content areas.
71

72
```typescript { .api }
73
/**
74
 * Main application frame providing structural layout
75
 * @param children - Content to display in the main area
76
 * @param navigation - Navigation component or configuration
77
 * @param topBar - Top bar component or configuration
78
 * @param logo - Logo configuration for the frame
79
 * @returns JSX element with frame structure
80
 */
81
function Frame(props: FrameProps): JSX.Element;
82

83
interface FrameProps {
84
  /** Content to display in the main content area */
85
  children: React.ReactNode;
86
  /** Navigation component for the sidebar */
87
  navigation?: React.ReactNode;
88
  /** Top bar component for the header */
89
  topBar?: React.ReactNode;
90
  /** Logo configuration */
91
  logo?: LogoProps;
92
  /** Skip to content link configuration */
93
  skipToContentTarget?: React.RefObject<HTMLElement>;
94
  /** Callback when navigation is dismissed on mobile */
95
  onNavigationDismiss?: () => void;
96
}
97

98
interface LogoProps {
99
  /** Logo image source */
100
  source: string;
101
  /** Logo width */
102
  width?: number;
103
  /** Logo accessibility label */
104
  accessibilityLabel?: string;
105
  /** Logo click handler */
106
  onClick?: () => void;
107
}
108
```
109

110
### Page
111

112
Page container component that provides consistent page structure with headers, breadcrumbs, and action areas.
113

114
```typescript { .api }
115
/**
116
 * Page container with headers, breadcrumbs, and actions
117
 * @param title - Page title text
118
 * @param subtitle - Optional subtitle text
119
 * @param children - Page content
120
 * @param breadcrumbs - Breadcrumb navigation items
121
 * @param primaryAction - Primary page action button
122
 * @param secondaryActions - Secondary action buttons
123
 * @returns JSX element with page structure
124
 */
125
function Page(props: PageProps): JSX.Element;
126

127
interface PageProps extends HeaderProps {
128
  /** The contents of the page */
129
  children?: React.ReactNode;
130
  /** Remove the normal max-width on the page */
131
  fullWidth?: boolean;
132
  /** Decreases the maximum layout width. Intended for single-column layouts */
133
  narrowWidth?: boolean;
134
}
135

136
interface HeaderProps extends TitleProps {
137
  /** Visually hide the title */
138
  titleHidden?: boolean;
139
  /** A label to use for the page when the page is ready, used by screen readers. Will override the title prop if present */
140
  pageReadyAccessibilityLabel?: string;
141
  /** Enables filtering action list items */
142
  filterActions?: boolean;
143
  /** Primary page-level action */
144
  primaryAction?: PrimaryAction | React.ReactNode;
145
  /** Page-level pagination */
146
  pagination?: PaginationProps;
147
  /** A back action link */
148
  backAction?: BreadcrumbsProps['backAction'];
149
  /** Collection of secondary page-level actions */
150
  secondaryActions?: MenuActionDescriptor[] | React.ReactNode;
151
  /** Collection of page-level groups of secondary actions */
152
  actionGroups?: MenuGroupDescriptor[];
153
  /** Additional meta data */
154
  additionalMetadata?: React.ReactNode | string;
155
  /** Callback that returns true when secondary actions are rolled up into action groups, and false when not */
156
  onActionRollup?(hasRolledUp: boolean): void;
157
}
158

159
interface TitleProps {
160
  /** Page title, in large type */
161
  title?: string;
162
  /** Page subtitle, in regular type */
163
  subtitle?: string;
164
  /** Important status information shown immediately after the title */
165
  titleMetadata?: React.ReactNode;
166
  /** Removes spacing between title and subtitle */
167
  compactTitle?: boolean;
168
}
169

170
interface PrimaryAction extends DestructableAction, DisableableAction, LoadableAction, IconableAction, TooltipAction {
171
  /** Provides extra visual weight and identifies the primary action in a set of buttons */
172
  primary?: boolean;
173
}
174
```
175

176
**Usage Example:**
177

178
```typescript
179
import React from 'react';
180
import { Page, Card, Button } from '@shopify/polaris';
181

182
function ProductPage() {
183
  const breadcrumbs = [
184
    { content: 'Products', url: '/products' }
185
  ];
186

187
  const primaryAction = {
188
    content: 'Save product',
189
    onAction: () => console.log('Product saved'),
190
  };
191

192
  const secondaryActions = [
193
    {
194
      content: 'Duplicate',
195
      onAction: () => console.log('Product duplicated'),
196
    },
197
    {
198
      content: 'Delete',
199
      destructive: true,
200
      onAction: () => console.log('Product deleted'),
201
    },
202
  ];
203

204
  return (
205
    <Page
206
      title="New Product"
207
      subtitle="Add a new product to your store"
208
      breadcrumbs={breadcrumbs}
209
      primaryAction={primaryAction}
210
      secondaryActions={secondaryActions}
211
    >
212
      <Card>
213
        {/* Page content */}
214
      </Card>
215
    </Page>
216
  );
217
}
218
```
219

220
### Layout
221

222
Responsive layout component for organizing page content into structured sections with consistent spacing.
223

224
```typescript { .api }
225
/**
226
 * Responsive layout component for organizing content
227
 * @param children - Layout sections
228
 * @param sectioned - Whether content is automatically sectioned
229
 * @returns JSX element with layout structure
230
 */
231
function Layout(props: LayoutProps): JSX.Element;
232

233
interface LayoutProps {
234
  /** Layout sections or content */
235
  children: React.ReactNode;
236
  /** Automatically wrap content in sections */
237
  sectioned?: boolean;
238
}
239

240
/**
241
 * Individual layout section component
242
 * @param children - Section content
243
 * @param secondary - Whether section is secondary (smaller width)
244
 * @param oneHalf - Whether section takes half width
245
 * @param oneThird - Whether section takes one-third width
246
 * @returns JSX element with section structure
247
 */
248
function LayoutSection(props: LayoutSectionProps): JSX.Element;
249

250
interface LayoutSectionProps {
251
  /** Section content */
252
  children?: React.ReactNode;
253
  /** Secondary section with reduced width */
254
  secondary?: boolean;
255
  /** Section takes half width */
256
  oneHalf?: boolean;
257
  /** Section takes one-third width */
258
  oneThird?: boolean;
259
  /** Full width section */
260
  fullWidth?: boolean;
261
}
262
```
263

264
**Usage Example:**
265

266
```typescript
267
import React from 'react';
268
import { Layout, Card, Text } from '@shopify/polaris';
269

270
function MyPage() {
271
  return (
272
    <Layout>
273
      <Layout.Section>
274
        <Card>
275
          <Text variant="bodyMd">Main content area</Text>
276
        </Card>
277
      </Layout.Section>
278
      <Layout.Section secondary>
279
        <Card>
280
          <Text variant="bodyMd">Secondary content area</Text>
281
        </Card>
282
      </Layout.Section>
283
    </Layout>
284
  );
285
}
286
```
287

288
### Toast Configuration
289

290
Toast notification system configuration and duration constants.
291

292
```typescript { .api }
293
/** Default duration for toast notifications in milliseconds */
294
const DEFAULT_TOAST_DURATION: number = 5000;
295

296
/** Default duration for toast notifications with actions in milliseconds */
297
const DEFAULT_TOAST_DURATION_WITH_ACTION: number = 10000;
298
```
299

300
## Core Types
301

302
```typescript { .api }
303
interface Action {
304
  /** Action content/label */
305
  content?: string;
306
  /** Accessibility label for screen readers */
307
  accessibilityLabel?: string;
308
  /** URL for link actions */
309
  url?: string;
310
  /** External link indicator */
311
  external?: boolean;
312
  /** Action callback function */
313
  onAction?(): void;
314
  /** Mouse enter handler */
315
  onMouseEnter?(): void;
316
  /** Touch start handler */
317
  onTouchStart?(): void;
318
}
319

320
interface TranslateOptions {
321
  /** Variables to interpolate into translation */
322
  [key: string]: string | number;
323
}
324

325
interface NumberFormatOptions {
326
  /** Currency code for currency formatting */
327
  currency?: string;
328
  /** Number formatting style */
329
  style?: 'decimal' | 'currency' | 'percent';
330
}
331

332
interface DateFormatOptions {
333
  /** Date formatting style */
334
  dateStyle?: 'full' | 'long' | 'medium' | 'short';
335
  /** Time formatting style */
336
  timeStyle?: 'full' | 'long' | 'medium' | 'short';
337
}
338
```
339

340
### ThemeProvider
341

342
Theme configuration component that provides theme context to child components, enabling custom theming and design token overrides.
343

344
```typescript { .api }
345
/**
346
 * Theme configuration provider for custom theming
347
 * @param theme - Theme configuration object
348
 * @param children - Components that will receive theme context
349
 * @returns JSX element with theme context
350
 */
351
function ThemeProvider(props: ThemeProviderProps): JSX.Element;
352

353
interface ThemeProviderProps {
354
  /** Custom theme configuration */
355
  theme?: Theme;
356
  /** The content to wrap with theme context */
357
  children?: React.ReactNode;
358
}
359
```
360

361
### PolarisTestProvider
362

363
Test utility component that provides Polaris context for testing environments, including mocked features and simplified configuration.
364

365
```typescript { .api }
366
/**
367
 * Test provider for Polaris components in testing environments
368
 * @param children - Components to test
369
 * @param options - Test configuration options
370
 * @returns JSX element with test context
371
 */
372
function PolarisTestProvider(props: PolarisTestProviderProps): JSX.Element;
373

374
interface PolarisTestProviderProps {
375
  /** The content to wrap with test context */
376
  children?: React.ReactNode;
377
  /** Test configuration options */
378
  options?: WithPolarisTestProviderOptions;
379
}
380

381
interface WithPolarisTestProviderOptions {
382
  /** Mock features configuration */
383
  features?: Partial<FeaturesConfig>;
384
  /** Mock theme configuration */
385
  theme?: Partial<Theme>;
386
  /** Mock i18n configuration */
387
  i18n?: Partial<I18nContext>;
388
  /** Media query mocks */
389
  mediaQuery?: {
390
    isNavigationCollapsed?: boolean;
391
  };
392
}
393
```
394

395
### AccountConnection
396

397
Account connection component for linking external services and managing connected account status with connection and disconnection actions.
398

399
```typescript { .api }
400
/**
401
 * Account connection component for external service integration
402
 * @param accountName - Name of the connected account
403
 * @param connected - Whether account is connected
404
 * @param action - Connection/disconnection action
405
 * @returns JSX element with account connection interface
406
 */
407
function AccountConnection(props: AccountConnectionProps): JSX.Element;
408

409
interface AccountConnectionProps {
410
  /** The name of the service */
411
  accountName?: string;
412
  /** The name of the connected account */
413
  connected: boolean;
414
  /** The title of the connection */
415
  title: React.ReactNode;
416
  /** Additional details about the connection */
417
  details?: React.ReactNode;
418
  /** Terms of service for the connection */
419
  termsOfService?: React.ReactNode;
420
  /** The action to connect or disconnect */
421
  action?: ComplexAction;
422
  /** URL to avatar image */
423
  avatarUrl?: string;
424
}