Insert a single entity
An API response contains one newly created record that should be inserted into normalized state.
Redux Toolkit · Module
adapter.setOne
setOne adds one entity to a createEntityAdapter state, or replaces the existing entity with the same ID. It accepts either a complete entity or an action carrying one.
How it works
setOne updates an entity-adapter state with one complete entity. If its ID is absent, it inserts the entity; if the ID already exists, it replaces that stored entity rather than merging selected fields.
Syntax
setOne<S extends EntityState<T>>(state: S, entity: T): S
setOne<S extends EntityState<T>>(state: S, action: PayloadAction<T>): SParameters
| Name | Type | Description |
|---|---|---|
state | S extends EntityState<T> | Normalized entity state managed by the adapter; it contains the entity lookup and ID collection. |
entity / action | T | PayloadAction<T> | One complete entity of the adapter's item type, or an action whose payload is that entity. |
Returns
The updated entity state, with the supplied entity added or replacing the entity with the same ID.
Key points
- The direct-call form takes an entity-adapter state and one complete entity, returning the updated state type.
- A reducer case can also receive a Redux action whose payload is the entity to insert or replace.
- The operation handles exactly one entity and chooses insertion or replacement based on whether its ID is present.
setOneis one of the generated CRUD reducer functions supplied by an entity adapter.- Pass the method as a case reducer or call it inside a case reducer when updating normalized state.
Common mistakes
- Unlike an update operation,
setOnereplaces an existing entity with the supplied complete entity; provide all fields the stored entity should retain.
Example: Insert or replace one entity
import { createEntityAdapter, createSlice } from '@reduxjs/toolkit'
type Book = { id: string; title: string }
const books = createEntityAdapter<Book>()
const booksSlice = createSlice({
name: 'books',
initialState: books.getInitialState(),
reducers: {
replaceBook(state, action: { payload: Book }) {
books.setOne(state, action.payload)
},
},
})
booksSlice.actions.replaceBook({ id: 'b1', title: 'Redux' })Use the adapter reducer inside a slice case reducer to insert an entity or replace the complete entity with the same ID.
When to use it
Replace stale entity data
A refreshed record should fully replace the currently stored record for the same ID.
Implement a slice case reducer
A slice reducer needs a concise CRUD operation for one entity without hand-writing normalized updates.
Interview questions
QWhat does setOne do when the entity ID already exists?
setOne accepts an entity-adapter state and either a complete entity or a Redux PayloadAction containing one. It adds the entity when its ID is new and replaces the existing entity when that ID is already present.
Follow-up: How would you preserve unspecified fields instead? Use updateOne with an { id, changes } update, because setOne is replacement-oriented rather than a partial merge.
QWhere can setOne be used?
The method is generated by createEntityAdapter, whose reducer functions operate on normalized entity state. It can be used as a case reducer in createSlice or as a mutating helper inside an Immer-powered reducer.
Follow-up: Why is direct mutation acceptable there? Redux Toolkit uses Immer in its reducer APIs, so the apparent mutation is converted into an immutable state update.
QWhat inputs does setOne accept?
Its TypeScript overloads accept either (state, entity) or (state, action), where the entity is the adapter's item type and the action payload contains that item. The operation returns the resulting entity state.
Follow-up: What must the adapter know to locate the item? It uses the configured ID selection, defaulting to the entity's id field unless a selectId option is supplied.
Related
createEntityAdapterEntityStateaddOneupdateOneupsertOneremoveOnegetInitialState