0
# Media & Icon Components
1

2
Image handling, icons, avatars, and media display components with responsive loading, accessibility features, and consistent styling. These components provide visual elements and media presentation for rich user interfaces.
3

4
## Capabilities
5

6
### Icon
7

8
Icon display component supporting various icon sources, colors, sizes, and accessibility features for visual communication.
9

10
```typescript { .api }
11
/**
12
 * Icon display component with color and size options
13
 * @param source - Icon source (component, placeholder, or string)
14
 * @param tone - Icon color tone
15
 * @param accessibilityLabel - Screen reader label
16
 * @returns JSX element with icon
17
 */
18
function Icon(props: IconProps): JSX.Element;
19

20
interface IconProps {
21
  /** Icon source */
22
  source: IconSource;
23
  /** Icon color tone */
24
  tone?: 'base' | 'disabled' | 'inherit' | 'emphasized' | 'caution' | 'warning' | 'critical' | 'success' | 'info' | 'magic';
25
  /** Accessibility label for screen readers */
26
  accessibilityLabel?: string;
27
}
28

29
/** Icon source type supporting multiple formats */
30
type IconSource = React.ComponentType<any> | 'placeholder' | string;
31
```
32

33
**Usage Example:**
34

35
```typescript
36
import React from 'react';
37
import { Icon, InlineStack, Text } from '@shopify/polaris';
38
import { 
39
  CheckIcon, 
40
  AlertIcon, 
41
  InfoIcon, 
42
  XIcon 
43
} from '@shopify/polaris-icons';
44

45
function IconExamples() {
46
  return (
47
    <InlineStack gap="400" align="center">
48
      <InlineStack gap="200" align="center">
49
        <Icon source={CheckIcon} tone="success" />
50
        <Text>Success</Text>
51
      </InlineStack>
52
      
53
      <InlineStack gap="200" align="center">
54
        <Icon source={AlertIcon} tone="warning" />
55
        <Text>Warning</Text>
56
      </InlineStack>
57
      
58
      <InlineStack gap="200" align="center">
59
        <Icon source={InfoIcon} tone="info" />
60
        <Text>Information</Text>
61
      </InlineStack>
62
      
63
      <InlineStack gap="200" align="center">
64
        <Icon source={XIcon} tone="critical" />
65
        <Text>Error</Text>
66
      </InlineStack>
67
    </InlineStack>
68
  );
69
}
70
```
71

72
### Avatar
73

74
User avatar component with support for images, initials, customer indicators, and various sizes.
75

76
```typescript { .api }
77
/**
78
 * User avatar with image, initials, and sizing options
79
 * @param size - Avatar size
80
 * @param name - User name for initials fallback
81
 * @param source - Avatar image source
82
 * @param customer - Customer avatar styling
83
 * @returns JSX element with avatar
84
 */
85
function Avatar(props: AvatarProps): JSX.Element;
86

87
interface AvatarProps {
88
  /** Avatar size */
89
  size?: 'extraSmall' | 'small' | 'medium' | 'large';
90
  /** Customer avatar indicator */
91
  customer?: boolean;
92
  /** User name for initials */
93
  name?: string;
94
  /** Avatar image source URL */
95
  source?: string;
96
  /** Accessibility label */
97
  accessibilityLabel?: string;
98
  /** Initial letters override */
99
  initials?: string;
100
  /** Shape variant */
101
  shape?: 'round' | 'square';
102
}
103
```
104

105
**Usage Example:**
106

107
```typescript
108
import React from 'react';
109
import { Avatar, InlineStack, Text, BlockStack } from '@shopify/polaris';
110

111
function AvatarExamples() {
112
  return (
113
    <BlockStack gap="400">
114
      <InlineStack gap="400" align="center">
115
        <Avatar
116
          customer
117
          name="Farrah"
118
          source="https://avatars.githubusercontent.com/u/12345"
119
        />
120
        <Text>Customer avatar with image</Text>
121
      </InlineStack>
122
      
123
      <InlineStack gap="400" align="center">
124
        <Avatar name="John Smith" size="large" />
125
        <Text>Avatar with initials</Text>
126
      </InlineStack>
127
      
128
      <InlineStack gap="400" align="center">
129
        <Avatar size="small" />
130
        <Text>Default avatar</Text>
131
      </InlineStack>
132
    </BlockStack>
133
  );
134
}
135
```
136

137
### Image
138

139
Responsive image component with loading states, alt text, and accessibility features for displaying media content.
140

141
```typescript { .api }
142
/**
143
 * Responsive image with loading states and accessibility
144
 * @param source - Image source URL
145
 * @param alt - Alternative text for accessibility
146
 * @returns JSX element with responsive image
147
 */
148
function Image(props: ImageProps): JSX.Element;
149

150
interface ImageProps {
151
  /** Image source URL */
152
  source: string;
153
  /** Alternative text */
154
  alt: string;
155
  /** Image width */
156
  width?: number;
157
  /** Image height */
158
  height?: number;
159
  /** Cross-origin attribute */
160
  crossOrigin?: 'anonymous' | 'use-credentials';
161
  /** Loading behavior */
162
  loading?: 'eager' | 'lazy';
163
  /** Decode behavior */
164
  decoding?: 'async' | 'sync' | 'auto';
165
  /** Image loading error handler */
166
  onError?: () => void;
167
  /** Image load handler */
168
  onLoad?: () => void;
169
  /** Additional CSS classes */
170
  className?: string;
171
  /** Draggable image */
172
  draggable?: boolean;
173
  /** Role override */
174
  role?: string;
175
  /** Tab index */
176
  tabIndex?: number;
177
}
178
```
179

180
### Thumbnail
181

182
Small preview image component with size options and transparency support for media previews.
183

184
```typescript { .api }
185
/**
186
 * Small preview image for media thumbnails
187
 * @param source - Thumbnail image source
188
 * @param alt - Alternative text
189
 * @param size - Thumbnail size
190
 * @returns JSX element with thumbnail image
191
 */
192
function Thumbnail(props: ThumbnailProps): JSX.Element;
193

194
interface ThumbnailProps {
195
  /** Thumbnail image source */
196
  source: string;
197
  /** Alternative text */
198
  alt: string;
199
  /** Thumbnail size */
200
  size?: 'extraSmall' | 'small' | 'medium' | 'large';
201
  /** Transparent background */
202
  transparent?: boolean;
203
}
204
```
205

206
### VideoThumbnail
207

208
Video preview thumbnail component for displaying video content previews with play indicators.
209

210
```typescript { .api }
211
/**
212
 * Video preview thumbnail with play indicator
213
 * @param videoLength - Video duration display
214
 * @param thumbnailUrl - Video thumbnail image
215
 * @param onClick - Thumbnail click handler
216
 * @returns JSX element with video thumbnail
217
 */
218
function VideoThumbnail(props: VideoThumbnailProps): JSX.Element;
219

220
interface VideoThumbnailProps {
221
  /** Video duration in seconds */
222
  videoLength?: number;
223
  /** Video thumbnail image URL */
224
  thumbnailUrl: string;
225
  /** Video title for accessibility */
226
  accessibilityLabel?: string;
227
  /** Play button click handler */
228
  onClick?: () => void;
229
  /** Show video duration */
230
  showVideoLength?: boolean;
231
  /** Video progress percentage */
232
  videoProgress?: number;
233
}
234
```
235

236
### Text Components
237

238
Text content and typography components for consistent text presentation and formatting.
239

240
```typescript { .api }
241
/**
242
 * Text content component with typography controls
243
 * @param children - Text content
244
 * @param variant - Typography variant
245
 * @param as - HTML element type
246
 * @returns JSX element with styled text
247
 */
248
function Text(props: TextProps): JSX.Element;
249

250
interface TextProps {
251
  /** Text content */
252
  children?: React.ReactNode;
253
  /** Typography variant */
254
  variant?: 
255
    | 'displayLarge' | 'displayMedium' | 'displaySmall' 
256
    | 'headingXl' | 'headingLg' | 'headingMd' | 'headingSm' | 'headingXs'
257
    | 'bodyLg' | 'bodyMd' | 'bodySm' | 'bodyXs'
258
    | 'captionLg' | 'captionMd' | 'captionSm';
259
  /** HTML element to render */
260
  as?: 'dt' | 'dd' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'strong' | 'em' | 'legend';
261
  /** Text alignment */
262
  alignment?: 'start' | 'center' | 'end' | 'justify';
263
  /** Font weight */
264
  fontWeight?: 'regular' | 'medium' | 'semibold' | 'bold';
265
  /** Text color */
266
  tone?: 'default' | 'subdued' | 'success' | 'critical' | 'warning' | 'highlight' | 'info';
267
  /** Text decoration */
268
  textDecorationLine?: 'line-through';
269
  /** Truncate text */
270
  truncate?: boolean;
271
  /** Breakword behavior */
272
  breakWord?: boolean;
273
  /** Numeric character variant */
274
  numeric?: boolean;
275
  /** Visuall hidden text */
276
  visuallyHidden?: boolean;
277
  /** Text ID */
278
  id?: string;
279
}
280

281
/**
282
 * Text container for spacing and typography hierarchy
283
 * @param children - Text content
284
 * @param spacing - Spacing between text elements
285
 * @returns JSX element with text container
286
 */
287
function TextContainer(props: TextContainerProps): JSX.Element;
288

289
interface TextContainerProps {
290
  /** Text content */
291
  children?: React.ReactNode;
292
  /** Spacing between elements */
293
  spacing?: 'tight' | 'loose';
294
}
295

296
/**
297
 * Inline code formatting component
298
 * @param children - Code content
299
 * @returns JSX element with inline code styling
300
 */
301
function InlineCode(props: InlineCodeProps): JSX.Element;
302

303
interface InlineCodeProps {
304
  /** Code content */
305
  children?: React.ReactNode;
306
}
307

308
/**
309
 * Text truncation component with expand/collapse
310
 * @param children - Content to truncate
311
 * @param width - Truncation width
312
 * @returns JSX element with truncation controls
313
 */
314
function Truncate(props: TruncateProps): JSX.Element;
315

316
interface TruncateProps {
317
  /** Content to truncate */
318
  children?: React.ReactNode;
319
  /** Truncation width */
320
  width?: string;
321
}
322

323
/**
324
 * Keyboard key display component
325
 * @param children - Key content
326
 * @param size - Key size
327
 * @returns JSX element styled as keyboard key
328
 */
329
function KeyboardKey(props: KeyboardKeyProps): JSX.Element;
330

331
interface KeyboardKeyProps {
332
  /** Key content */
333
  children?: React.ReactNode;
334
  /** Key size */
335
  size?: 'small' | 'medium' | 'large';
336
}
337
```
338

339
**Usage Example:**
340

341
```typescript
342
import React from 'react';
343
import { 
344
  Text, 
345
  TextContainer, 
346
  InlineCode, 
347
  KeyboardKey, 
348
  BlockStack,
349
  Image,
350
  Thumbnail
351
} from '@shopify/polaris';
352

353
function MediaTextExample() {
354
  return (
355
    <BlockStack gap="400">
356
      {/* Text examples */}
357
      <TextContainer>
358
        <Text variant="headingLg" as="h1">
359
          Product Documentation
360
        </Text>
361
        <Text variant="bodyMd" tone="subdued">
362
          Learn how to configure your product settings using the{' '}
363
          <InlineCode>product.config.js</InlineCode> file.
364
        </Text>
365
        <Text variant="bodySm">
366
          Press <KeyboardKey>⌘</KeyboardKey> + <KeyboardKey>S</KeyboardKey> to save.
367
        </Text>
368
      </TextContainer>
369

370
      {/* Image and thumbnail examples */}
371
      <BlockStack gap="200">
372
        <Image
373
          source="https://example.com/product-hero.jpg"
374
          alt="Product hero image"
375
          width={400}
376
          height={200}
377
        />
378
        
379
        <Thumbnail
380
          source="https://example.com/product-thumb.jpg"
381
          alt="Product thumbnail"
382
          size="large"
383
        />
384
      </BlockStack>
385
    </BlockStack>
386
  );
387
}
388
```
389

390
### Badge
391

392
Status and labeling component for displaying brief status information, progress indicators, and categorization.
393

394
```typescript { .api }
395
/**
396
 * Status and labeling component for brief information
397
 * @param children - Badge content
398
 * @param tone - Badge color theme
399
 * @param progress - Badge progress state
400
 * @returns JSX element with badge
401
 */
402
function Badge(props: BadgeProps): JSX.Element;
403

404
interface BadgeProps {
405
  /** Badge content */
406
  children?: React.ReactNode;
407
  /** Badge color tone */
408
  tone?: 'default' | 'success' | 'info' | 'attention' | 'warning' | 'critical';
409
  /** Badge progress state */
410
  progress?: 'incomplete' | 'partiallyComplete' | 'complete';
411
  /** Badge size */
412
  size?: 'small' | 'medium';
413
  /** Status value for tone */
414
  status?: ToneValue;
415
}
416

417
/** Tone value enum for badge status */
418
enum ToneValue {
419
  Default = 'default',
420
  Success = 'success',
421
  Info = 'info',
422
  Attention = 'attention', 
423
  Warning = 'warning',
424
  Critical = 'critical',
425
}
426

427
/** Progress value enum for badge progress */
428
enum ProgressValue {
429
  Incomplete = 'incomplete',
430
  PartiallyComplete = 'partiallyComplete',
431
  Complete = 'complete',
432
}
433
```
434

435
### Skeleton Components
436

437
Loading state components for displaying placeholder content while data is loading.
438

439
```typescript { .api }
440
/**
441
 * Page skeleton for loading states
442
 * @param title - Show title skeleton
443
 * @param breadcrumbs - Show breadcrumbs skeleton
444
 * @param primaryAction - Show primary action skeleton
445
 * @returns JSX element with page skeleton
446
 */
447
function SkeletonPage(props: SkeletonPageProps): JSX.Element;
448

449
interface SkeletonPageProps {
450
  /** Show title skeleton */
451
  title?: boolean;
452
  /** Show breadcrumbs skeleton */
453
  breadcrumbs?: boolean;
454
  /** Show primary action skeleton */
455
  primaryAction?: boolean;
456
  /** Show secondary actions skeleton */
457
  secondaryActions?: number;
458
  /** Page content */
459
  children?: React.ReactNode;
460
}
461

462
/**
463
 * Body text skeleton for loading content
464
 * @param lines - Number of text lines
465
 * @returns JSX element with text skeleton
466
 */
467
function SkeletonBodyText(props: SkeletonBodyTextProps): JSX.Element;
468

469
interface SkeletonBodyTextProps {
470
  /** Number of skeleton lines */
471
  lines?: number;
472
}
473

474
/**
475
 * Display text skeleton for headings
476
 * @param size - Display text size
477
 * @returns JSX element with display text skeleton
478
 */
479
function SkeletonDisplayText(props: SkeletonDisplayTextProps): JSX.Element;
480

481
interface SkeletonDisplayTextProps {
482
  /** Display text size */
483
  size?: 'small' | 'medium' | 'large' | 'extraLarge';
484
}
485

486
/**
487
 * Thumbnail skeleton for media placeholders
488
 * @param size - Thumbnail size
489
 * @returns JSX element with thumbnail skeleton
490
 */
491
function SkeletonThumbnail(props: SkeletonThumbnailProps): JSX.Element;
492

493
interface SkeletonThumbnailProps {
494
  /** Thumbnail size */
495
  size?: 'small' | 'medium' | 'large';
496
}
497

498
/**
499
 * Tabs skeleton for navigation placeholders
500
 * @param count - Number of tab skeletons
501
 * @returns JSX element with tabs skeleton
502
 */
503
function SkeletonTabs(props: SkeletonTabsProps): JSX.Element;
504

505
interface SkeletonTabsProps {
506
  /** Number of tab skeletons */
507
  count?: number;
508
}
509
```
510

511
### MediaCard
512

513
Legacy media card component for displaying media content with descriptions and actions.
514

515
```typescript { .api }
516
/**
517
 * Legacy media card for displaying media content
518
 * @param title - Card title
519
 * @param primaryAction - Main action for the card
520
 * @param description - Media description
521
 * @returns JSX element with media card display
522
 */
523
function MediaCard(props: { 
524
  title: string; 
525
  primaryAction: ComplexAction; 
526
  description: string; 
527
  popoverActions?: ComplexAction[]; 
528
  portrait?: boolean; 
529
  size?: 'small' | 'medium';
530
}): JSX.Element;
531
```
532

533
### Indicator
534

535
Visual indicator component for showing status, notifications, or highlighting interface elements.
536

537
```typescript { .api }
538
/**
539
 * Visual indicator for status and notifications
540
 * @param pulse - Whether to show pulsing animation
541
 * @returns JSX element with indicator
542
 */
543
function Indicator(props: IndicatorProps): JSX.Element;
544

545
interface IndicatorProps {
546
  /** Whether to pulse the indicator */
547
  pulse?: boolean;
548
}
549
```
550

551
### Tag
552

553
Removable tag component for displaying labels, categories, and selected filters with optional remove functionality.
554

555
```typescript { .api }
556
/**
557
 * Removable tag for labels and categories
558
 * @param children - Tag content
559
 * @param disabled - Whether tag is disabled
560
 * @param onRemove - Remove handler
561
 * @returns JSX element with tag display
562
 */
563
function Tag(props: TagProps): JSX.Element;
564

565
interface TagProps {
566
  /** Content to display in the tag */
567
  children?: React.ReactNode;
568
  /** Whether the tag is disabled */
569
  disabled?: boolean;
570
  /** Callback when the tag is removed */
571
  onRemove?(): void;
572
  /** Additional action for the tag */
573
  onClick?(): void;
574
  /** URL for the tag */
575
  url?: string;
576
  /** Accessibility label for the tag */
577
  accessibilityLabel?: string;
578
}
579
```
580

581
## Media Types and Utilities
582

583
```typescript { .api }
584
/** Heading tag name type for text elements */
585
type HeadingTagName = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
586

587
/** Icon source supporting various formats */
588
type IconSource = React.ComponentType<any> | 'placeholder' | string;
589

590
/** Image loading states */
591
type ImageLoadingState = 'loading' | 'loaded' | 'error';
592

593
/** Media query configuration for responsive behavior */
594
interface MediaQueryConfig {
595
  /** Small screen breakpoint */
596
  small: string;
597
  /** Medium screen breakpoint */
598
  medium: string;
599
  /** Large screen breakpoint */
600
  large: string;
601
}
602
```