Allow dataviews empty state to be customised

Author: p-jackson

packages/dataviews/README.md

@@ -421,6 +421,28 @@ A list of numbers used to control the available item counts per page.
 
 It's optional. Defaults to `[10, 20, 50, 100]`.
 
+#### `empty`: `Object`
+
+The empty object configures what should be shown when the `data` is empty.
+
+Example:
+
+```js
+const empty = {
+	heading: 'No pages found',
+	description: 'Your search did not match any pages.',
+	illustration: 'https://example.com/illustration.svg',
+	actions: <Button>Create a new page</Button>,
+};
+```
+
+Properties:
+
+-   `heading`: short message describing the empty state. If this is the only property provided then the empty state will render as plain text without any additional styling.
+-   `description`: a longer description of the empty state, providing more context or instructions.
+-   `illustration`: either a URL to an image or a React component that renders an illustration. This should be purely illustrative as it does not render with any alt text.
+-   `actions`: a `<Button>` (or list of `<Button>`s rendered in a fragment) which provide the user with next steps.
+
 ### Composition modes
 
 The `DataViews` component supports two composition modes:
@@ -451,6 +473,7 @@ The following components are available directly under `DataViews`:
 -   `DataViews.Pagination`
 -   `DataViews.BulkActionToolbar`
 -   `DataViews.ViewConfig`
+-   `DataViews.Empty`
 
 #### example
 

packages/dataviews/src/components/dataviews-context/index.ts

@@ -7,6 +7,7 @@ import type { ComponentProps, ReactElement } from 'react';
  * WordPress dependencies
  */
 import { createContext, createRef } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
@@ -17,6 +18,7 @@ import type {
 	NormalizedField,
 	SupportedLayouts,
 	NormalizedFilter,
+	EmptyViewProps,
 } from '../../types';
 import type { SetSelection } from '../../private-types';
 import { LAYOUT_TABLE } from '../../constants';
@@ -52,6 +54,11 @@ type DataViewsContextType< Item > = {
 	isShowingFilter: boolean;
 	setIsShowingFilter: ( value: boolean ) => void;
 	perPageSizes?: [ number, number, number, number ];
+	empty: EmptyViewProps;
+};
+
+export const DEFAULT_VIEW_EMPTY = {
+	heading: __( 'No results' ),
 };
 
 const DataViewsContext = createContext< DataViewsContextType< any > >( {
@@ -76,6 +83,7 @@ const DataViewsContext = createContext< DataViewsContextType< any > >( {
 	filters: [],
 	isShowingFilter: false,
 	setIsShowingFilter: () => {},
+	empty: DEFAULT_VIEW_EMPTY,
 } );
 
 export default DataViewsContext;

packages/dataviews/src/components/dataviews-empty/index.tsx

@@ -0,0 +1,60 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	__experimentalHStack as HStack,
+	__experimentalVStack as VStack,
+} from '@wordpress/components';
+import { useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import DataViewsContext from '../dataviews-context';
+import type { EmptyViewProps } from '../../types';
+
+function DataViewsEmptyContent( {
+	heading,
+	description,
+	illustration,
+	actions,
+}: EmptyViewProps ) {
+	if ( ! description && ! illustration && ! actions ) {
+		return heading;
+	}
+
+	const illustrationElement =
+		typeof illustration === 'string' ? (
+			<img
+				className="dataviews-empty__illustration"
+				src={ illustration }
+				alt=""
+			/>
+		) : (
+			illustration
+		);
+
+	return (
+		<VStack spacing={ 6 } alignment="center" className="dataviews-empty">
+			{ illustration && illustrationElement }
+			<VStack spacing={ 0 } alignment="center">
+				<div className="dataviews-empty__heading">{ heading }</div>
+				{ description && (
+					<div className="dataviews-empty__description">
+						{ description }
+					</div>
+				) }
+			</VStack>
+			{ actions && (
+				<HStack spacing={ 2 } justify="center">
+					{ actions }
+				</HStack>
+			) }
+		</VStack>
+	);
+}
+
+export function DataViewsEmpty() {
+	const { empty } = useContext( DataViewsContext );
+	return <DataViewsEmptyContent { ...empty } />;
+}

packages/dataviews/src/components/dataviews-empty/style.scss

@@ -0,0 +1,23 @@
+
+.dataviews-empty {
+	max-width: $modal-width-medium;
+	text-align: center;
+}
+
+.dataviews-empty__illustration {
+	width: 100%;
+}
+
+.dataviews-empty__heading {
+	color: $gray-900;
+	font-size: $font-size-large;
+	line-height: $font-line-height-large;
+	font-weight: $font-weight-medium;
+}
+
+.dataviews-empty__description {
+	color: $gray-700;
+	font-size: $font-size-medium;
+	line-height: $font-line-height-medium;
+	text-wrap: balance;
+}

packages/dataviews/src/components/dataviews/index.tsx

@@ -13,7 +13,7 @@ import { useMergeRefs, useResizeObserver } from '@wordpress/compose';
 /**
  * Internal dependencies
  */
-import DataViewsContext from '../dataviews-context';
+import DataViewsContext, { DEFAULT_VIEW_EMPTY } from '../dataviews-context';
 import {
 	default as DataViewsFilters,
 	useFilters,
@@ -23,13 +23,20 @@ import DataViewsLayout from '../dataviews-layout';
 import DataViewsFooter from '../dataviews-footer';
 import DataViewsSearch from '../dataviews-search';
 import { BulkActionsFooter } from '../dataviews-bulk-actions';
+import { DataViewsEmpty } from '../dataviews-empty';
 import { DataViewsPagination } from '../dataviews-pagination';
 import DataViewsViewConfig, {
 	DataviewsViewConfigDropdown,
 	ViewTypeMenu,
 } from '../dataviews-view-config';
 import { normalizeFields } from '../../normalize-fields';
-import type { Action, Field, View, SupportedLayouts } from '../../types';
+import type {
+	Action,
+	Field,
+	View,
+	SupportedLayouts,
+	EmptyViewProps,
+} from '../../types';
 import type { SelectionOrUpdater } from '../../private-types';
 type ItemWithId = { id: string };
 
@@ -60,6 +67,7 @@ type DataViewsProps< Item > = {
 	getItemLevel?: ( item: Item ) => number;
 	children?: ReactNode;
 	perPageSizes?: [ number, number, number, number ];
+	empty?: EmptyViewProps;
 } & ( Item extends ItemWithId
 	? { getItemId?: ( item: Item ) => string }
 	: { getItemId: ( item: Item ) => string } );
@@ -134,6 +142,7 @@ function DataViews< Item >( {
 	header,
 	children,
 	perPageSizes,
+	empty,
 }: DataViewsProps< Item > ) {
 	const containerRef = useRef< HTMLDivElement | null >( null );
 	const [ containerWidth, setContainerWidth ] = useState( 0 );
@@ -198,6 +207,7 @@ function DataViews< Item >( {
 				isShowingFilter,
 				setIsShowingFilter,
 				perPageSizes,
+				empty: empty ?? DEFAULT_VIEW_EMPTY,
 			} }
 		>
 			<div
@@ -226,6 +236,7 @@ const DataViewsSubComponents = DataViews as typeof DataViews & {
 	Pagination: typeof DataViewsPagination;
 	Search: typeof DataViewsSearch;
 	ViewConfig: typeof DataviewsViewConfigDropdown;
+	Empty: typeof DataViewsEmpty;
 };
 
 DataViewsSubComponents.BulkActionToolbar = BulkActionsFooter;
@@ -236,5 +247,6 @@ DataViewsSubComponents.LayoutSwitcher = ViewTypeMenu;
 DataViewsSubComponents.Pagination = DataViewsPagination;
 DataViewsSubComponents.Search = DataViewsSearch;
 DataViewsSubComponents.ViewConfig = DataviewsViewConfigDropdown;
+DataViewsSubComponents.Empty = DataViewsEmpty;
 
 export default DataViewsSubComponents;

packages/dataviews/src/components/dataviews/stories/index.story.tsx

@@ -20,6 +20,7 @@ import {
 	__experimentalText as Text,
 	__experimentalHStack as HStack,
 	__experimentalVStack as VStack,
+	Button,
 } from '@wordpress/components';
 import { __, _n } from '@wordpress/i18n';
 
@@ -110,6 +111,52 @@ export const Empty = () => {
 	);
 };
 
+export const CustomEmpty = () => {
+	const [ view, setView ] = useState< View >( {
+		...DEFAULT_VIEW,
+		fields: [ 'title', 'description', 'categories' ],
+	} );
+
+	return (
+		<DataViews
+			getItemId={ ( item ) => item.id.toString() }
+			paginationInfo={ { totalItems: 0, totalPages: 0 } }
+			data={ [] }
+			view={ view }
+			fields={ fields }
+			onChangeView={ setView }
+			actions={ actions }
+			defaultLayouts={ defaultLayouts }
+			empty={ {
+				heading: view.search ? 'No sites found' : 'No sites',
+				description: view.search
+					? `Your search for “${ view.search }” did not match any sites. Try searching by the site title or domain name.`
+					: 'Get started by creating a new site.',
+				illustration:
+					'https://pd.w.org/2025/05/9376819135a616da1.38400720-768x432.jpeg',
+				actions: (
+					<>
+						{ view.search && (
+							<Button
+								variant="secondary"
+								onClick={ () => {
+									setView( ( oldView ) => ( {
+										...oldView,
+										search: '',
+									} ) );
+								} }
+							>
+								Clear search
+							</Button>
+						) }
+						<Button variant="primary">Add new site</Button>
+					</>
+				),
+			} }
+		/>
+	);
+};
+
 export const FieldsNoSortableNoHidable = () => {
 	const [ view, setView ] = useState< View >( {
 		...DEFAULT_VIEW,
@@ -211,7 +258,16 @@ function PlanetOverview( { planets }: { planets: SpaceObject[] } ) {
 				</VStack>
 			</Grid>
 
-			<DataViews.Layout className="free-composition-dataviews-layout" />
+			{ planets.length > 0 ? (
+				<DataViews.Layout className="free-composition-dataviews-layout" />
+			) : (
+				<HStack
+					justify="space-around"
+					className="free-composition-dataviews-empty"
+				>
+					<DataViews.Empty />
+				</HStack>
+			) }
 		</>
 	);
 }
@@ -261,6 +317,13 @@ export const FreeComposition = () => {
 					table: {},
 					grid: {},
 				} }
+				empty={ {
+					heading: 'No plants',
+					description: `Try a different search because “${ view.search }” returned no results.`,
+					actions: (
+						<Button variant="secondary">Create new planet</Button>
+					),
+				} }
 			>
 				<PlanetOverview planets={ planets } />
 			</DataViews>

packages/dataviews/src/components/dataviews/stories/style.css

@@ -23,3 +23,9 @@
 .free-composition-dataviews-layout thead {
 	inset-block-start: 67px;
 }
+
+.free-composition-dataviews-empty > * {
+	border: 1px solid #000;
+	border-radius: 8px;
+	padding: 24px;
+}

packages/dataviews/src/dataviews-layouts/grid/index.tsx

@@ -38,6 +38,7 @@ import type {
 import type { SetSelection } from '../../private-types';
 import { ItemClickWrapper } from '../utils/item-click-wrapper';
 import { useUpdatedPreviewSizeOnViewportChange } from './preview-size-picker';
+import { DataViewsEmpty } from '../../components/dataviews-empty';
 const { Badge } = unlock( componentsPrivateApis );
 
 interface GridItemProps< Item > {
@@ -425,7 +426,7 @@ function ViewGrid< Item >( {
 							'dataviews-no-results': ! isLoading,
 						} ) }
 					>
-						<p>{ isLoading ? <Spinner /> : __( 'No results' ) }</p>
+						<p>{ isLoading ? <Spinner /> : <DataViewsEmpty /> }</p>
 					</div>
 				)
 			}

packages/dataviews/src/dataviews-layouts/list/index.tsx

@@ -3,6 +3,11 @@
  */
 import clsx from 'clsx';
 
+/**
+ * Internal dependencies
+ */
+import { DataViewsEmpty } from '../../components/dataviews-empty';
+
 /**
  * WordPress dependencies
  */
@@ -488,7 +493,7 @@ export default function ViewList< Item >( props: ViewListProps< Item > ) {
 				} ) }
 			>
 				{ ! hasData && (
-					<p>{ isLoading ? <Spinner /> : __( 'No results' ) }</p>
+					<p>{ isLoading ? <Spinner /> : <DataViewsEmpty /> }</p>
 				) }
 			</div>
 		);

packages/dataviews/src/dataviews-layouts/table/index.tsx

@@ -39,6 +39,7 @@ import type { SetSelection } from '../../private-types';
 import ColumnHeaderMenu from './column-header-menu';
 import ColumnPrimary from './column-primary';
 import { useIsHorizontalScrollEnd } from './use-is-horizontal-scroll-end';
+import { DataViewsEmpty } from '../../components/dataviews-empty';
 
 interface TableColumnFieldProps< Item > {
 	fields: NormalizedField< Item >[];
@@ -464,7 +465,7 @@ function ViewTable< Item >( {
 				id={ tableNoticeId }
 			>
 				{ ! hasData && (
-					<p>{ isLoading ? <Spinner /> : __( 'No results' ) }</p>
+					<p>{ isLoading ? <Spinner /> : <DataViewsEmpty /> }</p>
 				) }
 			</div>
 		</>