Chat - Selectors reference

Subscribe to exactly the store slices you need with selectors for efficient, granular rendering.

chatSelectors is a collection of selectors — several memoized — that read from the normalized chat store. They power the built-in hooks and can also be used directly with useChatStore() and useStore() for advanced subscriptions.

import { chatSelectors, useChatStore } from '@mui/x-chat/headless';

Direct state selectors

These selectors read a single field from the store and return it directly:

Derived selectors

These selectors combine multiple store fields. Array-building selectors memoize their result; the others return stored references or primitives, which are stable by construction:

Parameterized selectors

Using selectors with useChatStore()

The hooks useMessageIds(), useMessage(id), and others are convenience wrappers around useChatStore() + chatSelectors. When you need a custom derived value, use the store directly:

useChatStore() returns the chat Store instance. To subscribe a component to a selector, pass both to useStore() from @mui/x-internals/store — the same subscription utility the built-in hooks use internally. This import is the supported way to read the store with a selector.

import { useChatStore, chatSelectors } from '@mui/x-chat/headless';
import { createSelectorMemoized, useStore } from '@mui/x-internals/store';

const failedMessageCount = createSelectorMemoized(
  chatSelectors.messages,
  (messages) => messages.filter((message) => message.status === 'error').length,
);

function FailedMessageBadge() {
  const store = useChatStore();
  const count = useStore(store, failedMessageCount);

  return <span>{count} failed</span>;
}

Calling parameterized selectors

For selectors that take an argument, pass a selector function:

function ConversationTitle({ id }: { id: string }) {
  const store = useChatStore();
  const conversation = useStore(store, chatSelectors.conversation, id);
  const author = useStore(store, chatSelectors.messageAuthor, id, store.parameters);

  return <span>{conversation?.title ?? author?.displayName ?? 'Untitled'}</span>;
}

Memoization and reference stability

messages, conversations, messageAuthor, typingUserIds, and typingUserIdsForActiveConversation are built with createSelectorMemoized and return reference-equal results while their inputs are unchanged. message, conversation, and activeConversation use plain createSelector but return the stored record itself, so the reference only changes when that record updates. messageCount, conversationCount, and messageError return primitives or null-able stored values, where reference stability is moot.

createSelectorMemoized keeps a single-entry cache per store (maxSize: 1), so for the parameterized memoized selectors (messageAuthor, typingUserIds) reference equality only holds while consecutive calls use the same arguments — alternating IDs across many ad-hoc subscribers thrashes the single-entry cache. Each useStore subscription still avoids re-renders via its own equality handling; this caveat is about cross-subscriber cache hits, not correctness.

Why normalization matters

The store keeps messages and conversations in a normalized shape (ids + byId maps) rather than flat arrays. The design has three benefits:

• Point updates—updating a single message during streaming does not rebuild the message array. Only the messagesById record changes.
• Stable references—the messageIds array only changes when messages are added or removed, not when their content updates. useMessageIds() stays stable during streaming.
• Memoized derivation—the messages selector rebuilds the array only when either messageIds or messagesById changes, and the result is reference-equal when inputs are unchanged.

This is why the useMessageIds() + useMessage(id) pattern performs well for large threads—the ID list stays stable while individual rows subscribe to their own message record.

See also

• See Hooks reference for details.
• See Controlled state for details.
• See Performance for details.