@wordpress/widget-dashboard

Widget Dashboard

Stateless rendering engine for widget dashboards. WidgetDashboard renders an editable grid of widget instances behind a consumer-controlled edit mode: drag-to-reorder, resize, a modal inserter, per-widget settings, and command-palette integration.

The engine owns no data. Widget types flow in through the widgetTypes prop (see @wordpress/widget-primitives), the consumer owns the committed layout array, and in-progress edits accumulate in an internal staging layer until the user commits them, at which point onLayoutChange fires with the updated array. Grid placement renders through @wordpress/grid.

For how the widget system fits together (authoring, build, server registry, hosts), see the dashboard widget system architecture document.

Installation

Install the module:

npm install @wordpress/widget-dashboard --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Setup

Component styles are CSS Modules injected at runtime when a component mounts; there is no stylesheet to enqueue or import.

Visual defaults read the design tokens that @wordpress/theme publishes as --wpds-* CSS custom properties. In WordPress screens managed by Gutenberg the tokens stylesheet is loaded centrally and no setup is needed. Elsewhere, install and load it in your application:

npm install @wordpress/theme

import '@wordpress/theme/design-tokens.css';

Usage

import { useState } from '@wordpress/element';
import { WidgetDashboard } from '@wordpress/widget-dashboard';

function Dashboard() {
	const [ layout, setLayout ] = useState( defaultLayout );

	return (
		<WidgetDashboard
			layout={ layout }
			onLayoutChange={ setLayout }
			widgetTypes={ widgetTypes }
		/>
	);
}

<WidgetDashboard> renders <WidgetDashboard.Widgets /> by default. Pass children to compose the dashboard — header, empty state, footer — around the grid:

<WidgetDashboard
	layout={ layout }
	onLayoutChange={ setLayout }
	widgetTypes={ widgetTypes }
>
	<WidgetDashboard.NoWidgetsState>
		<p>{ __( 'No widgets yet.' ) }</p>
	</WidgetDashboard.NoWidgetsState>
	<WidgetDashboard.Widgets />
</WidgetDashboard>

Composition

The dashboard is built from two kinds of parts:

• Triggers and chrome you arrange. Actions, Widgets, WidgetChrome, NoWidgetsState, and Commands are compound components; compose them as children to place them in your layout.
• Overlays the engine mounts. The widget inserter, the per-widget settings editor, and the reset confirmation are mounted by the engine and driven by shared UI state. Triggers open them only through that state — the "Add widget" button and the command palette both open the inserter — so there is no overlay to place in the tree.

Omitting children renders the default arrangement. When you pass children, the overlays mount regardless of what you compose.

Properties

layout: DashboardWidget[]

Widget instances to render. Each instance carries a stable uuid, a type reference, optional attributes, and a placement describing its slot in the grid. The consumer owns this state.

onLayoutChange: ( layout: DashboardWidget[] ) => void

Called when the user commits in-progress edits via the Done action. Receives the full layout array as it should be persisted. In-progress mutations (reorder, resize, add, remove, attribute edits) accumulate in the dashboard's internal staging layer and do not fire this callback until commit.

onLayoutReset: () => void

Optional. Reset action surfaced by <WidgetDashboard.Actions /> and the command palette. When omitted, the reset entry points are disabled.

widgetTypes: WidgetType[]

The widget types available to the dashboard. The dashboard never queries a store directly — consumers scope and filter via this prop.

isResolvingWidgetTypes: boolean

Optional. When true, widget types are still loading: instances whose type is not yet in widgetTypes show a loading state instead of a missing state.

editMode: boolean

When true, the grid enables drag and resize. Defaults to false.

onEditChange: ( next: boolean ) => void

Optional. Called when edit mode toggles via WidgetDashboard.Actions (or any consumer-built toggle). When omitted, WidgetDashboard.Actions renders nothing.

resolveWidgetModule: ( moduleId: string ) => Promise< { default: ComponentType } >

Optional. Maps a WidgetType.renderModule id to the React component that renders the widget. Defaults to a dynamic import( /* webpackIgnore */ moduleId ). Override for tests, Storybook, or remote-URL loading.

gridSettings: WidgetGridSettings

Optional. Grid model configuration; see Grid settings. Defaults to DEFAULT_GRID.

children: ReactNode

Optional. Composition slot for the dashboard's triggers and chrome. When omitted, the engine renders the default arrangement: the empty state, the actions, the widgets grid, and the command palette integration. The engine-mounted overlays are present either way.

Compound components

<WidgetDashboard.Widgets />

Iterates layout, renders each entry through <WidgetDashboard.WidgetChrome />, and feeds the resulting tree into the underlying grid (@wordpress/grid).

<WidgetDashboard.WidgetChrome />

Per-instance wrapper. Provides widget identity to the render tree via context and hosts the widget's render module under a Suspense boundary and an error boundary. The instance is read from layout; consumers don't pass it manually.

<WidgetDashboard.NoWidgetsState>

Renders its children only when layout is empty. Pair it with <WidgetDashboard.Widgets /> so the empty state shows up in place of the grid until widgets are added.

<WidgetDashboard.Actions />

Edit-mode toggle: a "Customize" button while editMode is off, and "Add widget", "Cancel", "Done" while it is on. The buttons and the more-actions menu are triggers: "Customize" and "Done" fire onEditChange, "Add widget" opens the inserter, and "Reset to default" opens the reset confirmation. Returns null when the dashboard is mounted without onEditChange, so surfaces that don't expose edit mode can keep Actions in their tree unconditionally.

<WidgetDashboard.Commands />

Command palette integration. It registers the dashboard's commands through @wordpress/commands (customize, add widgets, reset to default) and sets the active command context. It renders nothing, and surfaces wherever the host application mounts the command palette. Ships in the default arrangement; when passing custom children, compose it to keep the integration.

<Page> from @wordpress/admin-ui exposes an actions slot used across admin screens (DataViews, WidgetDashboard, …). Plug Actions straight into it:

import { Page } from '@wordpress/admin-ui';

<WidgetDashboard
	layout={ layout }
	onLayoutChange={ setLayout }
	widgetTypes={ widgetTypes }
	editMode={ editMode }
	onEditChange={ setEditMode }
>
	<Page
		title={ __( 'My Dashboard' ) }
		actions={ <WidgetDashboard.Actions /> }
	>
		<WidgetDashboard.Widgets />
	</Page>
	<WidgetDashboard.Commands />
</WidgetDashboard>;

<Page> is optional. The compound renders inside any container, so a bare <header> or custom chrome works just as well.

Inserting widgets

The "Add widget" button in <WidgetDashboard.Actions /> opens a modal inserter. It lists every entry in the widgetTypes prop as a grid of live previews (each preview renders the type's example attributes through its own render module), supports search, and exposes a "Select" action with bulk support so users can insert one or several widgets in a single layout change.

On confirmation, the inserter creates instances (using each type's example.attributes as the initial values) and appends them to the staged layout. The dialog closes after a successful insertion or when the user dismisses it.

Grid settings

The dashboard supports two grid models, configured through the gridSettings prop: the 2D packed grid model, where tiles declare explicit spans over uniform rows, and the content-driven masonry model, where heights follow content and resize is horizontal-only. The settings are read-only for the dashboard: there is no in-dashboard editing UI. The consumer owns the values and their persistence.

The exported kit for handling them:

• WidgetGridSettings — discriminated union of the per-model settings shapes.
• DEFAULT_GRID — canonical default settings, applied when gridSettings is omitted.
• normalizeGridSettings( settings, defaultRowHeight ) — coerces legacy freeform row heights to the nearest preset. Run it over stored payloads before passing them in.
• ROW_HEIGHT_PRESETS / DEFAULT_ROW_HEIGHT — the row-height presets (small, medium, large) that rowHeight values normalize to.
• WIDGET_DASHBOARD_COLUMN_COUNT — maximum column count on wide containers. The effective count steps down from container width; persisted columns values are ignored.

<WidgetDashboard
	layout={ layout }
	onLayoutChange={ setLayout }
	widgetTypes={ widgetTypes }
	gridSettings={ { model: 'masonry' } }
/>

How this host translates the contract

This engine is one host implementation of @wordpress/widget-primitives. It maps contract fields to host-owned UI as follows.

Identity and help

When a widget type declares help, the tile chrome surfaces its content and optional links in a infotip beside the title.

Attribute editing

Hosts build settings UI from the declarative attributes schema. This host splits editing across two surfaces:

• Prominent surface: fields marked relevance: 'high' render inline in the tile chrome, for quick in-context edits.
• Settings surface: the full schema is available through a dedicated settings UI. When some attributes are not promoted to the prominent surface, a settings entry point exposes the rest; fields already promoted may still appear there.

When every attribute is 'high', no separate settings entry point is shown. A second surface would only repeat what the prominent surface already exposes.

Edits on either surface stage through the engine's internal layer and reach onLayoutChange on commit.

Authoring widgets

Widget render modules receive only what they need to render and edit:

interface WidgetRenderProps< Item = unknown > {
	attributes: Item;
	setAttributes?: ( next: Partial< Item > ) => void;
}

setAttributes flows back through the staging layer and reaches onLayoutChange on commit. Removal, badges, and error chrome are not part of this contract — those belong to the consumer.

Types

• DashboardWidget — a placement of a widget on the dashboard. Carries uuid, type, attributes, placement.
• WidgetGridSettings — grid model configuration; see Grid settings.

The widget contract types (WidgetName, WidgetType, WidgetRenderProps, ResolveWidgetModule) are defined in @wordpress/widget-primitives and imported from there directly; this engine does not re-export them.

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.