Chat - Core selectors

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

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

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

The following demo uses selectors for efficient rendering:

Selector reference

Direct state selectors

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

Derived selectors

These selectors combine multiple store fields and memoize the result:

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:

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

function MessageCounter() {
  const store = useChatStore();
  const count = useStore(store, chatSelectors.messageCount);

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

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);

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

Why normalization matters

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

1. Point updates — Updating a single message during streaming does not rebuild the message array. Only the messagesById record changes.
2. Stable references — The messageIds array only changes when messages are added or removed, not when their content updates. useMessageIds() stays stable during streaming.
3. 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

• Hooks for the hook API that wraps these selectors.
• State and store for the internal state shape and controlled/uncontrolled models.
• Advanced store access for a demo using useChatStore() with custom selectors.
• Selector-driven thread for the row-level subscription pattern in action.

API

• ChatRoot