Use lightning/stateManager* State Managers

Here 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.

1. Create an instance of a state manager using its factory (default) function.
2. Wait for the state manager to retrieve the expected data, or return an error.
3. If there's an error, handle it.
4. After the data is loaded, do something with it.

Create an instance of a built-in state manager using its factory (default) function. For example:

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.

• "unconfigured" — the state manager doesn’t have sufficient configuration information to proceed.
• "loading" — the state manager is in the process of obtaining data.
• "loaded" — the state manager has loaded data and set the data property.
• "error" — there was an error loading the data. The 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 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:

• Any record changes made by the Lightning Data Service (LDS) imperative updateRecord and deleteRecord functions
• Any record changes made via GraphQL mutations
• Changes detected as part of notifyRecordUpdateAvailable or getRecordNotifyChange processing
• Changes noticed while ingesting data from any other UI API call. For example, if you perform a getRecordUi 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:

The 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

• Example: Use a Built-in State Manager
• Best Practices for State Manager Design