shadcn-ui/ui · error · Error

MessageScrollerItem must be used within a MessageScroller.

Error message

MessageScrollerItem must be used within a MessageScroller.

What it means

useMessageScrollerItemContext reads MessageScrollerItemContext, which only <MessageScrollerItem> populates (registration data for a single message). Components that need per-item registration call this hook; outside a <MessageScrollerItem> (itself expected within a <MessageScroller>) the context is null and the hook throws, because there is no message to register.

Source

Thrown at packages/react/src/message-scroller/components.tsx:37

  React.createContext<MessageScrollerContextValue | null>(null)
const MessageScrollerItemContext =
  React.createContext<MessageScrollerRegisterMessage | null>(null)

function useMessageScrollerContext() {
  const context = React.useContext(MessageScrollerContext)

  if (!context) {
    throw new Error("useMessageScroller must be used within a MessageScroller.")
  }

  return context
}

function useMessageScrollerItemContext() {
  const context = React.useContext(MessageScrollerItemContext)

  if (!context) {
    throw new Error(
      "MessageScrollerItem must be used within a MessageScroller."
    )
  }

  return context
}

function useMessageScroller() {
  const { scrollToEnd, scrollToMessage, scrollToStart } =
    useMessageScrollerContext()

  return React.useMemo(
    () => ({
      scrollToEnd,
      scrollToMessage,
      scrollToStart,
    }),
    [scrollToEnd, scrollToMessage, scrollToStart]

View on GitHub (pinned to efac598707)

Solutions

Wrap each message row in <MessageScrollerItem>.
Ensure <MessageScrollerItem> itself is within <MessageScroller>.
Move item-consuming components back inside their <MessageScrollerItem>.

Example fix

// before
<MessageScroller>
  <MessageRow /> // consumes item context, no wrapper
</MessageScroller>

// after
<MessageScroller>
  <MessageScrollerItem>
    <MessageRow />
  </MessageScrollerItem>
</MessageScroller>

Defensive patterns

Strategy: validation

Validate before calling

function useOptionalMessageScrollerItem() {
  return React.useContext(MessageScrollerItemContext)
}
const item = useOptionalMessageScrollerItem()
if (!item) return null

Type guard

function useHasMessageScrollerItem(): boolean {
  return React.useContext(MessageScrollerItemContext) !== null
}

Prevention

Wrap each message row in <MessageScrollerItem> before consuming item context.
Ensure <MessageScrollerItem> is itself inside <MessageScroller>.
Keep item-consuming components within their item boundary.

When it happens

Trigger: Rendering a component that consumes MessageScrollerItemContext directly under <MessageScroller> but not inside <MessageScrollerItem>; using an item sub-component as a standalone; nesting it under the wrong provider.

Common situations: Building a custom message row and forgetting the <MessageScrollerItem> wrapper; refactor that drops the item boundary; portal content rendered outside the item.

Related errors

AI-assisted analysis of shadcn-ui/ui@efac598707 (2026-08-12). Data as JSON: /api/errors/f61556a79cc90119. Report an issue: GitHub.