${component} must be used within a Questionnaire.Choice comp

Error message

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

What it means

useQuestionnaireChoiceContext() reads QuestionnaireChoiceContext and throws if a Choice-scoped part is rendered outside a <Questionnaire.Choice> ancestor. The guard enforces the compound-component hierarchy: choice-related subparts only make sense inside a Choice.

Source

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

  React.createContext<QuestionnaireItemContextValue | null>(null)

function useQuestionnaireContext(component: string) {
  const context = React.useContext(QuestionnaireContext)

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

  return context
}

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
}

View on GitHub (pinned to efac598707)

Solutions

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

Example fix

// before
<Questionnaire.ChoiceLabel /> // throws: no Choice ancestor

// after
<Questionnaire.Root>
  <Questionnaire.Item>
    <Questionnaire.Choice>
      <Questionnaire.ChoiceLabel />
    </Questionnaire.Choice>
  </Questionnaire.Item>
</Questionnaire.Root>

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

import * as React from "react"
import { QuestionnaireChoiceContext } from "@/questionnaire/context"
function useOptionalChoice() {
  return React.useContext(QuestionnaireChoiceContext) // null when outside Choice
}

Prevention

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

When it happens

Trigger: Rendering Questionnaire.ChoiceLabel or another Choice-scoped part outside <Questionnaire.Choice>; restructuring JSX so the Choice wrapper is removed but its children remain.

Common situations: Composing custom Choice layouts and forgetting the Choice wrapper; testing a Choice subpart in isolation without a provider.

Related errors

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