# Updating Lists

When a request succeeds, you will frequently want to add the resources returned by the response to a [list](/resources/lists.md). There is a convenient way to do this using the [request actions](https://github.com/jamesplease/redux-resource/tree/e0d24c6c69879d54e94c1ab9976b4b6a9d5adb7f/docs/requests/requests/request-actions.md).

> Note: if you're not familiar with resource lists, then you may want to read [the documentation for them](/resources/lists.md) before continuing.

## Specifying a List

To specify the list to add the resources to, add the `list` property to a 'successful' [request action](/requests/request-actions.md).

```javascript
import { actionTypes } fom 'redux-resource';
import store from './store';

store.dispatch({
  type: actionTypes.READ_RESOURCES_SUCCEEDED,
  resourceType: 'books',
  list: 'mostPopular',
  requestKey: 'getMostPopular'
  // `newResources` is the list of books that were returned by the server
  // for this request.
  resources: newResources
});
```

You only need to specify a list for create or read *success* actions. Nothing happens if you specify a list for an update or delete action.

> Note: deleted resources will automatically be removed from any list that they are included in.

## Why Specify a List

There are two main reasons to specify a list when making a request. The [`getResources`](/api-reference/get-resources.md) function lets you quickly access resources given a list name.

For instance, if you specify the list `"favoriteBooks"` when a request succeeds for fetching a user's favorite books, then you can access the resources returned by that request using the following snippet:

```javascript
import { getResources } from 'redux-resource';
import store from './my-store';

const state = store.getState();
const favoriteBooks = getResources(state.books, 'favoriteBooks');
```

Convenience aside, lists enable you to do sligtly complicated, but common task that is more difficult to do otherwise. The situation it helps in is where the application fetches a collection of resources that the user can then modify.

An example may help demonstrate this. Consider a page that displays a user's favorite books. When the user navigates to the page, a request to fetch the favorite books is made.

After the request completes, the user is able to add or delete favorite books. After they add or delete a book, you want the favorite books that are displayed to them to reflect their changes.

There are two ways to do this:

1. after the create or delete request succeeds, you make a second request to fetch

   the list of favorite books a second time, so that the list is up-to-date
2. after the create or delete request succeeds, you update the local list of favorite books

   without making a second request

Both of these approaches are great. You can do whichever you think is best.

If you decide to go with the second method, then using a list makes this straightforward to do. It works like this: when the request to fetch the favorite books succeeds, you can add the resources to the `favoriteBooks` list. Then, when the user creates or deletes a new favorite book, you modify the list.

## Replacing List IDs

By default, subsequent requests with the same list will *merge* the old list IDs with the new IDs. You can replace the old list with the new by passing `mergeListIds: false` in your action. For instance:

```javascript
import { actionTypes } fom 'redux-resource';
import store from './store';

store.dispatch({
  type: actionTypes.READ_RESOURCES_SUCCEEDED,
  resourceType: 'books',
  list: 'mostPopular',
  mergeListIds: false,
  // `newResources` is the list of books that were returned by the server
  // for this request.
  resources: newResources
});
```

## More Reading

For more on lists, refer to [the lists guide](/resources/lists.md) and [the Lists FAQ](/faq/lists.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://redux-resource.js.org/requests/request-actions/updating-lists.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.