lightning/stateManager* State ManagersHere are details of how to create and use built-in state managers.
Setting aside best practices, the basic process of using a built-in state manager is the same for all the state managers.
In practice, if your usage pattern is this simple, use the wire service instead. To clearly illustrate the essential concepts here, we’ve over-simplified the example code in this topic. See Best Practices for State Manager Design for more guidance on how built-in state managers are intended to be used.
Important
Create an instance of a built-in state manager using its factory (default) function. For example:
1// ...
2import smRecord from "lightning/stateManagerRecord";
3import NAME_FIELD from "@salesforce/schema/Account.Name";
4import OWNER_NAME_FIELD from "@salesforce/schema/Account.Owner.Name";
5import PHONE_FIELD from "@salesforce/schema/Account.Phone";
6import INDUSTRY_FIELD from "@salesforce/schema/Account.Industry";
7
8export default class Example extends LightningElement {
9
10 @api theRecordId;
11
12 // Create an instance of `lightning/stateManagerRecord`
13 const myRecord = smRecord({
14 recordId: theRecordId,
15 fields: [NAME_FIELD, INDUSTRY_FIELD],
16 optionalFields: [PHONE_FIELD, OWNER_NAME_FIELD]
17 });
18
19 // ...
20}After it’s created, check the status of and access data in the state manager through the standard properties.
The factory function requires you to provide all required parameters at once. You can reconfigure a state manager instance with setConfig(), and provide difference values for all the same parameters. This function is available on all built-in state managers.
You can also update the configuration of a state manager instance by changing individual parameters as needed. Each parameter has its own set function.
For example, lightning/stateManagerObjectInfo has a single setParameter function, setObjectApiName(). lightning/stateManagerRelatedListRecords has several set functions, one for each parameter. The specific functions available are listed on the individual state manager reference topics.
All built-in state managers have the following properties.
data property.error property contains additional information.When the state manager status property is “loaded”, the data property is in a valid state, and can be used by consumers of the state manager. The form and structure of data depend on the specific state manager.
When the state manager status property is “error”, the error property is in a valid state, and contains details of the specific error. If there’s a configuration error with the state manager itself, for example, missing or invalid parameters used in the factory function, error is usually a simple string. If the error is with the request or response, error can be a FetchResponse. However, error handling is complex. See Handle Errors in Lightning Data Service for a thorough explanation.
State managers that expose data without a simple, concrete identity — such as a related list — expose an imperative refresh action. Call refresh() to force a state manager to fetch the latest data from the server.
These state managers expose refresh():
When you call refresh() on a state manager instance, it returns a Promise<void>.
1import { LightningElement, api } from "lwc";
2import smRelatedListRecords from "lightning/stateManagerRelatedListRecords";
3import CONTACT_NAME from "@salesforce/schema/Contact.Name";
4
5export default class RelatedContacts extends LightningElement {
6 @api recordId;
7
8 contacts = smRelatedListRecords({
9 parentRecordId: this.recordId,
10 relatedListId: "Contacts",
11 fields: [CONTACT_NAME],
12 });
13
14 async handleRefresh() {
15 await this.contacts.value.refresh();
16 }
17}You can call refresh() only when the state manager’s status is loaded. In that state, the state manager re-fetches data from the server. The status remains loaded during the refresh. The returned Promise resolves after the refreshed data is available on the state manager’s data property.
For any other status, refresh() rejects the returned Promise without fetching data.
Offline behavior for refresh() is undefined. Don’t rely on any specific behavior when the client is offline.
State managers are full participants in the reactivity system of the LWC Framework. However, there are a few nuances to understand how to ensure that your state managers are reactive in all the ways you expect.
Built-in state managers use the same underlying logic as wire adapters and react to the same changes as the wire adapters do. Specifically:
updateRecord and deleteRecord functionsnotifyRecordUpdateAvailable or getRecordNotifyChange processinggetRecordUi call and LDS notices that an object info has changed then any affected values on instances of the object info and object infos state managers are updated.The simplest kind of reactivity is triggering updates to a state manager by explicitly changing its configuration. See Configuration Functions.
Components that reference values from a changed state manager automatically refresh as needed.
To create a state manager that is reactive to values without requiring an explicit configuration change, wrap the dependent values in one of the state management functions, either atom() or computed(). You can do this when creating a state manager instance, using the factory function, or later by using one of the configuration functions.
For example, here’s a slightly modified excerpt from the Nested State Manager Example:
1import { defineState } from "@lwc/state";
2import smRecord from "lightning/stateManagerRecord";
3// ...
4export default defineState(({ atom, computed, setAtom }, recordId, objectApiName) => {
5 // This custom state manager's configuration is an `atom()`
6 const config = atom({ recordId, objectApiName });
7
8 // Changing the config uses the state management function `setAtom()`
9 const setRecordId = (recordId) =>
10 setAtom(config, { recordId, objectApiName: config.value.objectApiName });
11 const setObjectApiName = (objectApiName) =>
12 setAtom(config, { recordId: config.value.recordId, objectApiName });
13
14 // ...
15 // The custom state manager uses nested, built-in state managers.
16 // When the built-in state manager instance is created, it passes in
17 // the atom, `config`, so that `smRecord` will automatically be
18 // updated anytime the config changes.
19 const initialRecord = smRecord(
20 computed([config], ({ recordId, objectApiName } = {}) => {
21 // ...
22 // IMPORTANT: This code is slightly revised for clarity;
23 // See the original sample for complete syntaxThe stateManagerRecord instance is part of the implementation of the custom state manager. It’s reactive to changes in the custom state manager’s configuration because the configuration smRecord receives in its factory function is an atom().
State managers, including built-in state managers, react to updates that take place through Lightning Data Service (LDS). (Subject to implementation details explained in the preceding section.)
State managers can’t react to changes that happen outside of LWC Framework reactivity mechanisms. For example, imperative Apex calls that change data.
See Also
Release Preview
j