${component} must be used within a Questionnaire.Item compon

Error message

${component} must be used within a Questionnaire.Item component.

What it means

useQuestionnaireItemContext() reads QuestionnaireItemContext and throws if an Item-scoped part is rendered outside a <Questionnaire.Item> ancestor. The guard enforces that item-related subparts are only used within an Item.

Source

Thrown at packages/react/src/questionnaire/context.ts:44

}

function useQuestionnaireChoiceContext(component: string) {
  const context = React.useContext(QuestionnaireChoiceContext)

  if (!context) {
    throw new Error(
      `${component} must be used within a Questionnaire.Choice component.`
    )
  }

  return context
}

function useQuestionnaireItemContext(component: string) {
  const context = React.useContext(QuestionnaireItemContext)

  if (!context) {
    throw new Error(
      `${component} must be used within a Questionnaire.Item component.`
    )
  }

  return context
}

export {
  QuestionnaireChoiceContext,
  QuestionnaireContext,
  QuestionnaireItemContext,
  useQuestionnaireChoiceContext,
  useQuestionnaireContext,
  useQuestionnaireItemContext,
}

View on GitHub (pinned to efac598707)

Solutions

Wrap the part in <Questionnaire.Item>...
In tests, render the part inside an Item (and its required ancestors).
Move the offending part under an Item in the JSX.

Example fix

// before
<Questionnaire.ItemTitle /> // throws: no Item ancestor

// after
<Questionnaire.Root>
  <Questionnaire.Item>
    <Questionnaire.ItemTitle />
  </Questionnaire.Item>
</Questionnaire.Root>

Defensive patterns

Strategy: validation

Validate before calling

import * as React from "react"
import { QuestionnaireItemContext } from "@/questionnaire/context"
const ctx = React.useContext(QuestionnaireItemContext)
if (!ctx) return null // render nothing instead of throwing

Type guard

import * as React from "react"
import { QuestionnaireItemContext } from "@/questionnaire/context"
function useOptionalItem() {
  return React.useContext(QuestionnaireItemContext) // null when outside Item
}

Prevention

Always render Item-scoped parts inside <Questionnaire.Item>.
In tests, render parts inside the full ancestor chain (Root > Item).
Co-locate Item subparts so they are not imported bare.

When it happens

Trigger: Rendering an Item-scoped Questionnaire part outside <Questionnaire.Item>; restructuring JSX so the Item wrapper is removed but its children remain.

Common situations: Building custom item layouts and forgetting the Item wrapper; testing an Item subpart in isolation without a provider.

Related errors

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