Chat - Core selectors

Read from the chat store with memoized selectors that drive granular, efficient subscriptions.

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

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

The demo below shows selectors driving row-level subscriptions in a chat thread:

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

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

  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