Title: @wordpress/widget-primitives
Published: June 16, 2026

---

# @wordpress/widget-primitives

## In this article

 * [Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#installation)
 * [Setup](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#setup)
 * [Public API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#public-api)
 * [Architecture](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#architecture)
 * [Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#contributing-to-this-package)

[ Back to top](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#wp--skip-link--target)

 This package is still experimental. “Experimental” means this is an early implementation
subject to drastic and breaking changes.

The host-agnostic toolkit for dashboard widgets: the contract types that define

what a widget is, plus the runtime to discover the registered widget types and resolve
their render modules. It belongs to no host.

## 󠀁[Installation](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#installation)󠁿

Install the module:

    ```bash
    npm install @wordpress/widget-primitives --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](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#setup)󠁿

This package ships no stylesheets and injects no styles; there is nothing
 to enqueue
or import.

The contract types and `<WidgetRender>` work in any React application. The
 `useWidgetTypes()`
hook reads the `widgetModule` entity through `@wordpress/core-data`, so it expects
to run against a WordPress site that exposes the `/wp/v2/widget-modules` REST endpoint.

## 󠀁[Public API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#public-api)󠁿

 * `<WidgetRender>`: canonical entry point for any host that mounts a widget.
    Resolves
   the widget’s render module via a host-provided `resolveWidgetModule` and mounts
   the resulting component with the standard `attributes` plus `setAttributes` render
   contract. Suspense, error handling, and chrome are host concerns and live outside
   the package.
 * `useWidgetTypes()`  `[ widgetTypes, isResolvingWidgetTypes ]`: the
    `WidgetType[]`
   available on the current page, plus a flag that is true while they are still 
   resolving.
 * Contract types: `WidgetType`, `WidgetName`, `WidgetIcon`,
    `WidgetRenderProps`,`
   ResolveWidgetModule`. `WidgetIcon` is a rendered SVG element (typically one from`
   @wordpress/icons`); hosts pass it to their icon primitive as is.

## 󠀁[Architecture](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#architecture)󠁿

For how the full pipeline fits together (authoring, build, server registry, and

hosts), see the [dashboard widget system architecture document](https://github.com/WordPress/gutenberg/blob/HEAD/docs/explanations/architecture/dashboard-widgets.md).

## 󠀁[Contributing to this package](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widget-primitives/?output_format=md#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](https://www.npmjs.com/)
and used by [WordPress](https://make.wordpress.org/core/) 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](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

First published

June 16, 2026

Last updated

June 16, 2026

Edit article

[ Improve it on GitHub: @wordpress/widget-primitives ](https://github.com/WordPress/gutenberg/edit/trunk/packages/widget-primitives/README.md)

[  Previous: @wordpress/warning](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-warning/)

[  Next: @wordpress/widgets](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-widgets/)