[!NOTE]
@udecode/zustood
has been renamed tozustand-x
. Using Jotai? See JotaiX.
Zustand is a small, fast and scalable state-management solution battle-tested against common pitfalls, like the dreaded zombie child problem, react concurrency, and context loss between mixed renderers. It may be the one state-manager in the React space that gets all of these right.
As zustand
is un-opinionated by design, it's challenging to find out the
best patterns to use when creating stores, often leading to boilerplate
code.
zustand-x
, built on top of zustand
, is providing a powerful store factory
which solves these challenges, so you can focus on your app.
yarn add zustand@4.4.7 zustand-x
[!IMPORTANT]
zustand
4.5.0+ is not yet supported. See https://github.com/udecode/zustand-x/issues/79.
Visit zustand-x.udecode.dev for the API.
zustand-x
in addition to zustand
?immer
, devtools
and persist
middlewaresreact-tracked
supportimport { createStore } from 'zustand-x'
const repoStore = createStore('repo')({
name: 'zustandX',
stars: 0,
owner: {
name: 'someone',
email: 'someone@xxx.com',
},
})
Note that the zustand store is accessible through:
// hook store
repoStore.useStore
// vanilla store
repoStore.store
Use the hooks in React components, no providers needed. Select your
state and the component will re-render on changes. Use the use
method:
repoStore.use.name()
repoStore.use.stars()
We recommend using the global hooks (see below) to support ESLint hook linting.
Big thanks for react-tracked
Use the tracked hooks in React components, no providers needed. Select your
state and the component will trigger re-renders only if the accessed property is changed. Use the useTracked
method:
repoStore.useTracked.owner()
Don't overuse hooks. If you don't need to subscribe to the state, use
instead the get
method:
repoStore.get.name()
repoStore.get.stars()
You can also get the whole state:
repoStore.get.state()
You generally want to write derived selectors (those depending on other selectors) for reusability. ZustandX supports extending selectors with full typescript support:
const repoStore = createStore('repo')({
name: 'zustandX',
stars: 0,
middlewares: ['immer', 'devtools', 'persist']
})
.extendSelectors((state, get, api) => ({
validName: () => get.name().trim(),
// other selectors
}))
.extendSelectors((state, get, api) => ({
// get.validName is accessible
title: (prefix: string) =>
`${prefix + get.validName()} with ${get.stars()} stars`,
}))
// extend again...
Update your store from anywhere by using the set
method:
repoStore.set.name('new name')
repoStore.set.stars(repoStore.get.stars + 1)
You can update the whole state from your app:
store.set.state((draft) => {
draft.name = 'test';
draft.stars = 1;
});
However, you generally want to create derived actions for reusability. ZustandX supports extending actions with full typescript support:
const repoStore = createStore('repo')({
name: 'zustandX',
stars: 0,
})
.extendActions((set, get, api) => ({
validName: (name: string) => {
set.name(name.trim());
},
// other actions
}))
.extendActions((set, get, api) => ({
reset: (name: string) => {
// set.validName is accessible
set.validName(name);
set.stars(0);
},
}))
// extend again...
After having created many stores, it can be difficult to remember which one to import. By combining all the stores, selectors and actions, just pick what you need using TS autocomplete.
import { mapValuesKey } from 'zustand-x';
// Global store
export const rootStore = {
auth: authStore,
combobox: comboboxStore,
contextMenu: contextMenuStore,
editor: editorStore,
modal: modalStore,
repo: repoStore,
toolbar: toolbarStore,
};
// Global hook selectors
export const useStore = () => mapValuesKey('use', rootStore);
// Global tracked hook selectors
export const useTrackedStore = () => mapValuesKey('useTracked', rootStore);
// Global getter selectors
export const store = mapValuesKey('get', rootStore);
// Global actions
export const actions = mapValuesKey('set', rootStore);
import shallow from 'zustand/shallow'
useStore().repo.name()
useStore().modal.isOpen()
// prevent unnecessary re-renders
// more see: https://docs.pmnd.rs/zustand/recipes#selecting-multiple-state-slices
useStore().repo.middlewares(shallow)
// with useTrackStore UserEmail Component will only re-render when accessed property owner.email changed
const UserEmail = () => {
const owner = useTrackedStore().repo.owner()
return (
<div>
<span>User Email: {owner.email}</span>
</div>
);
};
// with useStore UserEmail Component re-render when owner changed, but you can pass equalityFn to avoid it.
const UserEmail = () => {
const owner = useStore().repo.owner()
// const owner = useStore().repo.owner((prev, next) => prev.email === next.email)
return (
<div>
<span>User Email: {owner.email}</span>
</div>
);
};
By using useStore() or useTrackStore()
, ESLint will correctly lint hook errors.
store.repo.name()
store.modal.isOpen()
These can be used anywhere.
actions.repo.stars(store.repo.stars + 1)
actions.modal.open()
These can be used anywhere.
The second parameter of createStore
is for options:
export interface CreateStoreOptions<T extends State> {
middlewares?: any[];
devtools?: DevtoolsOptions;
immer?: ImmerOptions;
persist?: PersistOptions;
}
ZustandX is using these middlewares:
immer
: required. Autofreeze can be enabled using
immer.enabledAutoFreeze
option.devtools
: enabled if devtools.enabled
option is true
.persist
: enabled if persist.enabled
option is true
. persist
implements PersistOptions
interface from
zustandmiddlewares
optionDiscussions is the best place for bringing opinions and contributions. Letting us know if we're going in the right or wrong direction is great feedback and will be much appreciated!
🌟 Stars and 📥 Pull requests are welcome! Don't hesitate to share your feedback here. Read our contributing guide to get started.
Generated using TypeDoc