@wordpress/core-data
Advanced tools
Core Data is a data module intended to simplify access to and manipulation of core WordPress entities. It registers its own store and provides a number of selectors which resolve data from the WordPress REST API automatically, along with dispatching action creators to manipulate data. Core data is shipped with TypeScript definitions for WordPress data types.
Used in combination with features of the data module such as subscribe or higher-order components, it enables a developer to easily add data into the logic and display of their plugin.
Install the module
npm install @wordpress/core-data --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.
Below is an example of a component which simply renders a list of authors:
const { useSelect } = wp.data;
function MyAuthorsListBase() {
const authors = useSelect( ( select ) => {
return select( 'core' ).getUsers( { who: 'authors' } );
}, [] );
if ( ! authors ) {
return null;
}
return (
<ul>
{ authors.map( ( author ) => (
<li key={ author.id }>{ author.name }</li>
) ) }
</ul>
);
}
An entity represents a data source. Each item within the entity is called an entity record. Available entities are defined in rootEntitiesConfig at ./src/entities.js.
As of right now, the default entities defined by this package map to the REST API handbook, though there is nothing in the design that prevents it from being used to interact with any other API.
What follows is a description of some of the properties of rootEntitiesConfig.
'/wp/v2/users'.This property maps the entity to a given endpoint, taking its relative URL as value.
object.{ context: 'edit' }.Additional parameters to the request, added as a query string. Each property will be converted into a field/value pair. For example, given the baseURL: '/wp/v2/users' and the baseURLParams: { context: 'edit' } the URL would be /wp/v2/users?context=edit.
string.'slug'.The entity engine aims to convert the API response into a number of entity records. Responses can come in different shapes, which are processed differently.
Responses that represent a single object map to a single entity record. For example:
{
"title": "...",
"description": "...",
"...": "..."
}
Responses that represent a collection shaped as an array, map to as many entity records as elements of the array. For example:
[
{ "id": 1, "name": "...", "...": "..." },
{ "id": 2, "name": "...", "...": "..." },
{ "id": 3, "name": "...", "...": "..." }
]
There are also cases in which a response represents a collection shaped as an object, whose key is one of the property's values. Each of the nested objects should be its own entity record. For this case not to be confused with single object/entities, the entity configuration must provide the property key that holds the value acting as the object key. In the following example, the slug property's value is acting as the object key, hence the entity config must declare key: 'slug' for each nested object to be processed as an individual entity record:
{
"publish": { "slug": "publish", "name": "Published", "...": "..." },
"draft": { "slug": "draft", "name": "Draft", "...": "..." },
"future": { "slug": "future", "name": "Future", "...": "..." }
}
Entity records are unique. For entities that are collections, it's assumed that each record has an id property which serves as an identifier to manage it. If the entity defines a key, that property would be used as its identifier instead of the assumed id.
string.user.The name of the entity. To be used in the utilities that interact with it (selectors, actions, hooks).
string.root.Entities can be grouped by kind. To be used in the utilities that interact with them (selectors, actions, hooks).
The package provides general methods to interact with the entities (getEntityRecords, getEntityRecord, etc.) by leveraging the kind and name properties:
// Get the record collection for the user entity.
wp.data.select( 'core' ).getEntityRecords( 'root', 'user' );
// Get a single record for the user entity.
wp.data.select( 'core' ).getEntityRecord( 'root', 'user', recordId );
string.statuses.In addition to the general utilities (getEntityRecords, getEntityRecord, etc.), the package dynamically creates nicer-looking methods to interact with the entity records of the root kind, both the collection and single records. Compare the general and nicer-looking methods as follows:
// Collection
wp.data.select( 'core' ).getEntityRecords( 'root', 'user' );
wp.data.select( 'core' ).getUsers();
// Single record
wp.data.select( 'core' ).getEntityRecord( 'root', 'user', recordId );
wp.data.select( 'core' ).getUser( recordId );
Sometimes, the pluralized form of an entity is not regular (it is not formed by adding a -s suffix). The plural property of the entity config allows to declare an alternative pluralized form for the dynamic methods created for the entity. For example, given the status entity that declares the statuses plural, there are the following methods created for it:
// Collection
wp.data.select( 'core' ).getStatuses();
// Single record
wp.data.select( 'core' ).getStatus( recordId );
The following set of dispatching action creators are available on the object returned by wp.data.dispatch( 'core' ):
Returns an action object used in adding new entities.
Parameters
Array: Entities received.Returns
Object: Action object.Action triggered to delete an entity record.
Parameters
string: Kind of the deleted entity.string: Name of the deleted entity.number|string: Record ID of the deleted entity.?Object: Special query parameters for the DELETE API call.[Object]: Delete options.[Function]: Internal use only. Function to call instead of apiFetch(). Must return a promise.[boolean]: If false, this action suppresses all the exceptions. Defaults to false.Returns an action object that triggers an edit to an entity record.
Parameters
string: Kind of the edited entity record.string: Name of the edited entity record.number|string: Record ID of the edited entity record.Object: The edits.Object: Options for the edit.[boolean]: Whether to ignore the edit in undo history or not.Returns
Object: Action object.Returns an action object used to set the template for a given query.
Parameters
Object: The lookup query.string: The resolved template id.Returns
Object: Action object.Returns an action object used in signalling that entity records have been received.
Parameters
string: Kind of the received entity record.string: Name of the received entity record.Array|Object: Records received.?Object: Query Object.?boolean: Should invalidate query caches.?Object: Edits to reset.?Object: Meta information about pagination.Returns
Object: Action object.Returns an action object signalling that the fallback Navigation Menu id has been received.
Parameters
integer: the id of the fallback Navigation MenuReturns
Object: Action object.Action triggered to receive revision items.
Parameters
string: Kind of the received entity record revisions.string: Name of the received entity record revisions.number|string: The key of the entity record whose revisions you want to fetch.Array|Object: Revisions received.?Object: Query Object.?boolean: Should invalidate query caches.?Object: Meta information about pagination.Deprecated since WP 5.9, this is not useful anymore, use the selector directly.
Returns an action object used in signalling that the index has been received.
Returns
Object: Action object.Deprecated since WP 5.9, use receiveUserPermission instead.
Returns an action object used in signalling that Upload permissions have been received.
Parameters
boolean: Does the user have permission to upload files?Returns
Object: Action object.Action triggered to redo the last undone edit to an entity record, if any.
Action triggered to save an entity record's edits.
Parameters
string: Kind of the entity.string: Name of the entity.Object: ID of the record.Object=: Saving options.Action triggered to save an entity record.
Parameters
string: Kind of the received entity.string: Name of the received entity.Object: Record to be saved.Object: Saving options.[boolean]: Whether this is an autosave.[Function]: Internal use only. Function to call instead of apiFetch(). Must return a promise.[boolean]: If false, this action suppresses all the exceptions. Defaults to false.Action triggered to undo the last edit to an entity record, if any.
The following selectors are available on the object returned by wp.data.select( 'core' ):
Returns whether the current user can perform the given action on the given REST resource.
Calling this may trigger an OPTIONS request to the REST API via the canUser() resolver.
https://developer.wordpress.org/rest-api/reference/
Parameters
State: Data state.string: Action to check. One of: 'create', 'read', 'update', 'delete'.string | EntityResource: Entity resource to check. Accepts entity object { kind: 'root', name: 'media', id: 1 } or REST base as a string - media.EntityRecordKey: Optional ID of the rest resource to check.Returns
boolean | undefined: Whether or not the user can perform the action, or undefined if the OPTIONS request is still being made.Returns whether the current user can edit the given entity.
Calling this may trigger an OPTIONS request to the REST API via the canUser() resolver.
https://developer.wordpress.org/rest-api/reference/
Parameters
State: Data state.string: Entity kind.string: Entity name.EntityRecordKey: Record's id.Returns
boolean | undefined: Whether or not the user can edit, or undefined if the OPTIONS request is still being made.Deprecated since 11.3. Callers should use
select( 'core' ).getUsers({ who: 'authors' })instead.
Returns all available authors.
Parameters
State: Data state.GetRecordsHttpQuery: Optional object of query parameters to include with request. For valid query parameters see the Users page in the REST API Handbook and see the arguments for List Users and Retrieve a User.Returns
ET.User[]: Authors list.Returns the autosave for the post and author.
Parameters
State: State tree.string: The type of the parent post.EntityRecordKey: The id of the parent post.EntityRecordKey: The id of the author.Returns
EntityRecord | undefined: The autosave for the post and author.Returns the latest autosaves for the post.
May return multiple autosaves since the backend stores one autosave per author for each post.
Parameters
State: State tree.string: The type of the parent post.EntityRecordKey: The id of the parent post.Returns
Array< any > | undefined: An array of autosaves for the post, or undefined if there is none.Retrieve the list of registered block pattern categories.
Parameters
State: Data state.Returns
Array< any >: Block pattern category list.Retrieve the list of registered block patterns.
Parameters
State: Data state.Returns
Array< any >: Block pattern list.Return the current theme.
Parameters
State: Data state.Returns
any: The current theme.Deprecated since WordPress 6.5.0. Callers should use
select( 'core' ).getRevisions( 'root', 'globalStyles', ${ recordKey } )instead, whererecordKeyis the id of the global styles parent post.
Returns the revisions of the current global styles theme.
Parameters
State: Data state.Returns
Array< object > | null: The current global styles.Returns the current user.
Parameters
State: Data state.Returns
ET.User< 'edit' >: Current user object.Returns the default template use to render a given query.
Parameters
State: Data state.TemplateQuery: Query.Returns
string: The default template id for the given query.Returns the specified entity record, merged with its edits.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
ET.Updatable< EntityRecord > | false: The entity record, merged with its edits.Returns the embed preview for the given URL.
Parameters
State: Data state.string: Embedded URL.Returns
any: Undefined if the preview has not been fetched, otherwise, the preview fetched from the embed preview API.Deprecated since WordPress 6.0. Use getEntitiesConfig instead
Returns the loaded entities for the given kind.
Parameters
State: Data state.string: Entity kind.Returns
Array< any >: Array of entities with config matching kind.Returns the loaded entities for the given kind.
Parameters
State: Data state.string: Entity kind.Returns
Array< any >: Array of entities with config matching kind.Deprecated since WordPress 6.0. Use getEntityConfig instead
Returns the entity config given its kind and name.
Parameters
State: Data state.string: Entity kind.string: Entity name.Returns
any: Entity configReturns the entity config given its kind and name.
Parameters
State: Data state.string: Entity kind.string: Entity name.Returns
any: Entity configReturns the Entity's record object by key. Returns null if the value is not yet received, undefined if the value entity is known to not exist, or the entity object if it exists and is received.
Parameters
State: State treestring: Entity kind.string: Entity name.EntityRecordKey: Optional record's key. If requesting a global record (e.g. site settings), the key can be omitted. If requesting a specific item, the key must always be included.GetRecordsHttpQuery: Optional query. If requesting specific fields, fields must always include the ID. For valid query parameters see the Reference in the REST API Handbook and select the entity kind. Then see the arguments available "Retrieve a [Entity kind]".Returns
EntityRecord | undefined: Record.Returns the specified entity record's edits.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
Optional< any >: The entity record's edits.Returns the specified entity record's non transient edits.
Transient edits don't create an undo level, and are not considered for change detection. They are defined in the entity's config.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
Optional< any >: The entity record's non transient edits.Returns the Entity's records.
Parameters
State: State treestring: Entity kind.string: Entity name.GetRecordsHttpQuery: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the Reference in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s".Returns
EntityRecord[] | null: Records.Returns the Entity's total available records for a given query (ignoring pagination).
Parameters
State: State treestring: Entity kind.string: Entity name.GetRecordsHttpQuery: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the Reference in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s".Returns
number | null: number | null.Returns the number of available pages for the given query.
Parameters
State: State treestring: Entity kind.string: Entity name.GetRecordsHttpQuery: Optional terms query. If requesting specific fields, fields must always include the ID. For valid query parameters see the Reference in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s".Returns
number | null: number | null.Returns the specified entity record's last delete error.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
any: The entity record's save error.Returns the specified entity record's last save error.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
any: The entity record's save error.Returns the entity's record object by key, with its attributes mapped to their raw values.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record's key.Returns
EntityRecord | undefined: Object with the entity's raw attributes.Deprecated since 6.3
Returns the next edit from the current undo offset for the entity records edits history, if any.
Parameters
State: State tree.Returns
Optional< any >: The edit.Returns a new reference when edited values have changed. This is useful in inferring where an edit has been made between states by comparison of the return values using strict equality.
Usage
const hasEditOccurred = (
getReferenceByDistinctEdits( beforeState ) !==
getReferenceByDistinctEdits( afterState )
);
Parameters
Returns
Returns a single, specific revision of a parent entity.
Parameters
State: State treestring: Entity kind.string: Entity name.EntityRecordKey: The key of the entity record whose revisions you want to fetch.EntityRecordKey: The revision's key.GetRecordsHttpQuery: Optional query. If requesting specific fields, fields must always include the ID. For valid query parameters see revisions schema in the REST API Handbook. Then see the arguments available "Retrieve a [entity kind]".Returns
RevisionRecord | Record< PropertyKey, never > | undefined: Record.Returns an entity's revisions.
Parameters
State: State treestring: Entity kind.string: Entity name.EntityRecordKey: The key of the entity record whose revisions you want to fetch.GetRecordsHttpQuery: Optional query. If requesting specific fields, fields must always include the ID. For valid query parameters see revisions schema in the REST API Handbook. Then see the arguments available "Retrieve a [Entity kind]".Returns
RevisionRecord[] | null: Record.Return theme supports data in the index.
Parameters
State: Data state.Returns
any: Index data.Deprecated since 6.3
Returns the previous edit from the current undo offset for the entity records edits history, if any.
Parameters
State: State tree.Returns
Optional< any >: The edit.Retrieve the registered user pattern categories.
Parameters
State: Data state.Returns
Array< UserPatternCategory >: User patterns category array.Returns all the users returned by a query ID.
Parameters
State: Data state.string: Query ID.Returns
ET.User< 'edit' >[]: Users list.Returns true if the specified entity record has edits, and false otherwise.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
boolean: Whether the entity record has edits or not.Returns true if records have been received for the given set of parameters, or false otherwise.
Parameters
State: State treestring: Entity kind.string: Entity name.GetRecordsHttpQuery: Optional terms query. For valid query parameters see the Reference in the REST API Handbook and select the entity kind. Then see the arguments available for "List [Entity kind]s".Returns
boolean: Whether entity records have been received.Returns true if the REST request for autosaves has completed.
Parameters
State: State tree.string: The type of the parent post.EntityRecordKey: The id of the parent post.Returns
boolean: True if the REST request was completed. False otherwise.Returns true if there is a next edit from the current undo offset for the entity records edits history, and false otherwise.
Parameters
State: State tree.Returns
boolean: Whether there is a next edit or not.Returns true if there is a previous edit from the current undo offset for the entity records edits history, and false otherwise.
Parameters
State: State tree.Returns
boolean: Whether there is a previous edit or not.Returns true if the specified entity record is autosaving, and false otherwise.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
boolean: Whether the entity record is autosaving or not.Returns true if the specified entity record is deleting, and false otherwise.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
boolean: Whether the entity record is deleting or not.Determines if the returned preview is an oEmbed link fallback.
WordPress can be configured to return a simple link to a URL if it is not embeddable. We need to be able to determine if a URL is embeddable or not, based on what we get back from the oEmbed preview API.
Parameters
State: Data state.string: Embedded URL.Returns
boolean: Is the preview for the URL an oEmbed link fallback.Returns true if a request is in progress for embed preview data, or false otherwise.
Parameters
State: Data state.string: URL the preview would be for.Returns
boolean: Whether a request is in progress for an embed preview.Returns true if the specified entity record is saving, and false otherwise.
Parameters
State: State tree.string: Entity kind.string: Entity name.EntityRecordKey: Record ID.Returns
boolean: Whether the entity record is saving or not.The following set of react hooks available to import from the @wordpress/core-data package:
Hook that returns block content getters and setters for the nearest provided entity of the specified type.
The return value has the shape [ blocks, onInput, onChange ]. onInput is for block changes that don't create undo levels or dirty the post, non-persistent changes, and onChange is for persistent changes. They map directly to the props of a BlockEditorProvider and are intended to be used with it, or similar components or hooks.
Parameters
string: The entity kind.string: The entity name.Object:[string]: An entity ID to use instead of the context-provided one.Returns
[unknown[], Function, Function]: The block array and setters.Hook that returns the ID for the nearest provided entity of the specified type.
Parameters
string: The entity kind.string: The entity name.Hook that returns the value and a setter for the specified property of the nearest provided entity of the specified type.
Parameters
string: The entity kind.string: The entity name.string: The property name.[number|string]: An entity ID to use instead of the context-provided one.Returns
[*, Function, *]: An array where the first item is the property value, the second is the setter and the third is the full value object from REST API containing more information like raw, rendered and protected props.Resolves the specified entity record.
Usage
import { useEntityRecord } from '@wordpress/core-data';
function PageTitleDisplay( { id } ) {
const { record, isResolving } = useEntityRecord( 'postType', 'page', id );
if ( isResolving ) {
return 'Loading...';
}
return record.title;
}
// Rendered in the application:
// <PageTitleDisplay id={ 1 } />
In the above example, when PageTitleDisplay is rendered into an
application, the page and the resolution details will be retrieved from
the store state using getEntityRecord(), or resolved if missing.
import { useCallback } from 'react';
import { useDispatch } from '@wordpress/data';
import { __ } from '@wordpress/i18n';
import { TextControl } from '@wordpress/components';
import { store as noticeStore } from '@wordpress/notices';
import { useEntityRecord } from '@wordpress/core-data';
function PageRenameForm( { id } ) {
const page = useEntityRecord( 'postType', 'page', id );
const { createSuccessNotice, createErrorNotice } =
useDispatch( noticeStore );
const setTitle = useCallback(
( title ) => {
page.edit( { title } );
},
[ page.edit ]
);
if ( page.isResolving ) {
return 'Loading...';
}
async function onRename( event ) {
event.preventDefault();
try {
await page.save();
createSuccessNotice( __( 'Page renamed.' ), {
type: 'snackbar',
} );
} catch ( error ) {
createErrorNotice( error.message, { type: 'snackbar' } );
}
}
return (
<form onSubmit={ onRename }>
<TextControl
__nextHasNoMarginBottom
__next40pxDefaultSize
label={ __( 'Name' ) }
value={ page.editedRecord.title }
onChange={ setTitle }
/>
<button type="submit">{ __( 'Save' ) }</button>
</form>
);
}
// Rendered in the application:
// <PageRenameForm id={ 1 } />
In the above example, updating and saving the page title is handled
via the edit() and save() mutation helpers provided by
useEntityRecord();
Parameters
string: Kind of the entity, e.g. root or a postType. See rootEntitiesConfig in ../entities.ts for a list of available kinds.string: Name of the entity, e.g. plugin or a post. See rootEntitiesConfig in ../entities.ts for a list of available names.string | number: ID of the requested entity record.Options: Optional hook options.Returns
EntityRecordResolution< RecordType >: Entity record data.Changelog
6.1.0 Introduced in WordPress core.
Resolves the specified entity records.
Usage
import { useEntityRecords } from '@wordpress/core-data';
function PageTitlesList() {
const { records, isResolving } = useEntityRecords( 'postType', 'page' );
if ( isResolving ) {
return 'Loading...';
}
return (
<ul>
{ records.map( ( page ) => (
<li>{ page.title }</li>
) ) }
</ul>
);
}
// Rendered in the application:
// <PageTitlesList />
In the above example, when PageTitlesList is rendered into an
application, the list of records and the resolution details will be retrieved from
the store state using getEntityRecords(), or resolved if missing.
Parameters
string: Kind of the entity, e.g. root or a postType. See rootEntitiesConfig in ../entities.ts for a list of available kinds.string: Name of the entity, e.g. plugin or a post. See rootEntitiesConfig in ../entities.ts for a list of available names.Record< string, unknown >: Optional HTTP query description for how to fetch the data, passed to the requested API endpoint.Options: Optional hook options.Returns
EntityRecordsResolution< RecordType >: Entity records data.Changelog
6.1.0 Introduced in WordPress core.
Resolves resource permissions.
Usage
import { useResourcePermissions } from '@wordpress/core-data';
function PagesList() {
const { canCreate, isResolving } = useResourcePermissions( {
kind: 'postType',
name: 'page',
} );
if ( isResolving ) {
return 'Loading ...';
}
return (
<div>
{ canCreate ? <button>+ Create a new page</button> : false }
// ...
</div>
);
}
// Rendered in the application:
// <PagesList />
import { useResourcePermissions } from '@wordpress/core-data';
function Page( { pageId } ) {
const { canCreate, canUpdate, canDelete, isResolving } =
useResourcePermissions( {
kind: 'postType',
name: 'page',
id: pageId,
} );
if ( isResolving ) {
return 'Loading ...';
}
return (
<div>
{ canCreate ? <button>+ Create a new page</button> : false }
{ canUpdate ? <button>Edit page</button> : false }
{ canDelete ? <button>Delete page</button> : false }
// ...
</div>
);
}
// Rendered in the application:
// <Page pageId={ 15 } />
In the above example, when PagesList is rendered into an
application, the appropriate permissions and the resolution details will be retrieved from
the store state using canUser(), or resolved if missing.
Parameters
string | EntityResource: Entity resource to check. Accepts entity object { kind: 'root', name: 'media', id: 1 } or REST base as a string - media.IdType: Optional ID of the resource to check, e.g. 10. Note: This argument is discouraged when using an entity object as a resource to check permissions and will be ignored.Returns
ResourcePermissionsResolution< IdType >: Entity records data.Changelog
6.1.0 Introduced in WordPress core.
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.
FAQs
Access to and manipulation of core WordPress entities.
We found that @wordpress/core-data demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.