Data display components are used to present information to users in various visual formats, from simple text and icons to complex data visualizations.
Loading States
Spinner
Notifies users that their action is being processed.
import { Spinner } from '@wordpress/components';
function LoadingExample() {
return (
<div>
<Spinner />
<p>Loading content...</p>
</div>
);
}
The Spinner displays an animated circular loading indicator. It automatically uses theme colors and is accessible with proper ARIA attributes.
Usage:
- Loading initial content
- Processing actions
- Waiting for API responses
Storybook: Spinner
ProgressBar
Shows determinate progress for long-running operations.
import { __experimentalProgressBar as ProgressBar } from '@wordpress/components';
import { useState, useEffect } from '@wordpress/element';
function UploadProgress() {
const [progress, setProgress] = useState(0);
useEffect(() => {
const interval = setInterval(() => {
setProgress((prev) => Math.min(prev + 10, 100));
}, 500);
return () => clearInterval(interval);
}, []);
return <ProgressBar value={progress} />;
}
Props:
value?: number - Progress percentage (0-100)
Icons & Avatars
Icon
Displays SVG icons from the WordPress icon library or custom SVGs.
import { Icon } from '@wordpress/components';
import { check, closeSmall, wordpress } from '@wordpress/icons';
function IconExamples() {
return (
<>
<Icon icon={check} />
<Icon icon={wordpress} size={48} />
<Icon icon={closeSmall} size={24} />
</>
);
}
Props:
icon: IconType | SVGElement - Icon component or SVG
size?: number - Icon size in pixels
Storybook: Icon
Dashicon
Legacy icon component for WordPress Dashicons.
import { Dashicon } from '@wordpress/components';
function DashiconExample() {
return <Dashicon icon="admin-users" size={20} />;
}
Deprecated: Use Icon with @wordpress/icons instead. Dashicon is maintained for backward compatibility.
Avatar
Displays user profile images or initials.
import { Avatar } from '@wordpress/components';
function UserAvatar() {
return (
<>
<Avatar
name="John Doe"
src="https://example.com/avatar.jpg"
size={48}
/>
<Avatar
name="Jane Smith"
size={32}
/>
</>
);
}
Props:
name?: string - User name (shows initials if no image)
src?: string - Avatar image URL
size?: number - Avatar size in pixels
AvatarGroup
Displays multiple avatars in a group.
import { AvatarGroup } from '@wordpress/components';
function TeamAvatars() {
return (
<AvatarGroup
avatars={[
{ name: 'Alice', src: 'https://example.com/alice.jpg' },
{ name: 'Bob', src: 'https://example.com/bob.jpg' },
{ name: 'Charlie', src: 'https://example.com/charlie.jpg' },
{ name: 'Diana' },
{ name: 'Eve' },
]}
maxAvatars={3}
/>
);
}
Props:
avatars: Array<AvatarProps> - Array of avatar objects
maxAvatars?: number - Maximum visible avatars (shows +N for overflow)
Status Indicators
Badge
Small label for status, counts, or categories.
import { __experimentalBadge as Badge } from '@wordpress/components';
function StatusBadges() {
return (
<>
<Badge>New</Badge>
<Badge intent="info">Beta</Badge>
<Badge intent="success">Published</Badge>
<Badge intent="warning">Draft</Badge>
<Badge intent="error">Error</Badge>
</>
);
}
Props:
intent?: 'default' | 'info' | 'success' | 'warning' | 'error' - Badge color scheme
children: ReactNode - Badge content
Indicator
Simple colored dot for status indication.
import { __experimentalIndicator as Indicator } from '@wordpress/components';
function OnlineStatus() {
return (
<div>
<Indicator isPrimary />
<span>User is online</span>
</div>
);
}
Text Display
Text
Typography component for consistent text styling.
import { __experimentalText as Text } from '@wordpress/components';
function TextExamples() {
return (
<>
<Text size="body">Regular body text</Text>
<Text size="caption" isBlock>
Caption text
</Text>
<Text weight={600}>Bold text</Text>
<Text variant="muted">Muted text</Text>
</>
);
}
Props:
size?: 'body' | 'caption' | 'footnote' | 'largeTitle' | 'title' - Text size
weight?: number - Font weight (100-900)
variant?: 'default' | 'muted' - Text style variant
isBlock?: boolean - Display as block element
truncate?: boolean - Truncate with ellipsis
Heading
Semantic heading component with consistent styling.
import { __experimentalHeading as Heading } from '@wordpress/components';
function HeadingExamples() {
return (
<>
<Heading level={1}>Main Title</Heading>
<Heading level={2}>Subtitle</Heading>
<Heading level={3} weight={400}>Section</Heading>
</>
);
}
Props:
level: 1 | 2 | 3 | 4 | 5 | 6 - Heading level (required)
weight?: number - Font weight
color?: string - Text color
Truncate
Truncates text with ellipsis.
import { __experimentalTruncate as Truncate } from '@wordpress/components';
function TruncatedText() {
return (
<Truncate numberOfLines={2}>
This is a very long text that will be truncated after two lines.
Any content beyond the specified number of lines will be hidden
and replaced with an ellipsis.
</Truncate>
);
}
Props:
numberOfLines?: number - Maximum number of lines (default: 1)
limit?: number - Maximum character count
ellipsizeMode?: 'auto' | 'head' | 'tail' | 'middle' - Ellipsis position
Color Display
ColorIndicator
Displays a color swatch.
import { ColorIndicator } from '@wordpress/components';
function ColorDisplay() {
return (
<div>
<ColorIndicator colorValue="#ff0000" />
<span>Primary Red</span>
</div>
);
}
Props:
colorValue: string - Color value (hex, rgb, named)
GradientPicker
Displays gradient previews and allows gradient selection.
import { GradientPicker } from '@wordpress/components';
import { useState } from '@wordpress/element';
function MyGradientPicker() {
const [gradient, setGradient] = useState(
'linear-gradient(135deg, #667eea 0%, #764ba2 100%)'
);
return (
<GradientPicker
value={gradient}
onChange={setGradient}
gradients={[
{
name: 'Purple',
gradient: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
slug: 'purple',
},
{
name: 'Blue',
gradient: 'linear-gradient(135deg, #00c6ff 0%, #0072ff 100%)',
slug: 'blue',
},
]}
/>
);
}
ExternalLink
Link that opens in a new tab with proper accessibility.
import { ExternalLink } from '@wordpress/components';
function DocumentationLink() {
return (
<ExternalLink href="https://wordpress.org/gutenberg/">
Visit Gutenberg Docs
</ExternalLink>
);
}
Automatically adds:
target="_blank"
rel="noopener noreferrer"
- External link icon
- Screen reader text
Storybook: ExternalLink
FocalPointPicker
Interactive control for selecting image focal point.
import { FocalPointPicker } from '@wordpress/components';
import { useState } from '@wordpress/element';
function ImageFocalPoint() {
const [focalPoint, setFocalPoint] = useState({ x: 0.5, y: 0.5 });
return (
<FocalPointPicker
url="https://example.com/image.jpg"
value={focalPoint}
onChange={setFocalPoint}
/>
);
}
Props:
url: string - Image URL
value: { x: number, y: number } - Focal point (0-1 range)
onChange: (value) => void - Change handler
Placeholder
Placeholder component for empty states.
import { Placeholder } from '@wordpress/components';
import { wordpress } from '@wordpress/icons';
function EmptyState() {
return (
<Placeholder
icon={wordpress}
label="No content yet"
instructions="Add your first item to get started"
>
<Button variant="primary">Add Item</Button>
</Placeholder>
);
}
Props:
icon?: IconType - Placeholder icon
label?: string - Main label
instructions?: string - Instructional text
children?: ReactNode - Actions or additional content
Storybook: Placeholder
Sandbox
Safely renders HTML content in an iframe.
import { SandBox } from '@wordpress/components';
function HTMLPreview() {
const html = '<h1>Hello World</h1><p>This is sandboxed HTML</p>';
return <SandBox html={html} />;
}
Props:
html: string - HTML content to render
title?: string - Iframe title
styles?: string - Additional CSS styles
The Sandbox component isolates potentially unsafe HTML in an iframe, preventing it from affecting the parent page.
Data Visualization
For complex data visualization and tables, consider using:
- DataViews from
@wordpress/dataviews - Table and grid views with sorting, filtering, and actions
- FormTokenField - Token/tag input for displaying multiple items
Accessibility
All data display components include proper ARIA labels and roles:
- Spinner includes
role="presentation" and focusable="false"
- Avatar includes fallback to initials with proper contrast
- ColorIndicator uses accessible color contrast checking
- ExternalLink announces external destination to screen readers
Resources