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

Error message

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

What it means

useQuestionnaireContext() reads the QuestionnaireContext; if a Questionnaire subcomponent that uses this hook is rendered outside a <Questionnaire.Root> provider, the context is null and the hook throws. It is the standard 'hook used outside its provider' guard for the Root-scoped parts.

Source

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

import type {
  QuestionnaireChoiceContextValue,
  QuestionnaireContextValue,
  QuestionnaireItemContextValue,
} from "./types"

const QuestionnaireChoiceContext =
  React.createContext<QuestionnaireChoiceContextValue | null>(null)
const QuestionnaireContext =
  React.createContext<QuestionnaireContextValue | null>(null)
const QuestionnaireItemContext =
  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
}

View on GitHub (pinned to efac598707)

Solutions

Wrap the Questionnaire tree in <Questionnaire.Root>...</Questionnaire.Root>.
For tests, render the part inside a Root (or a manual provider).
Move the offending part under the Root in the JSX tree.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

import * as React from "react"
import { QuestionnaireContext } from "@/questionnaire/context"
// inside a component: peek without throwing
const ctx = React.useContext(QuestionnaireContext)
if (!ctx) return null // render nothing instead of throwing

Type guard

import * as React from "react"
import { QuestionnaireContext } from "@/questionnaire/context"
function useOptionalQuestionnaire() {
  return React.useContext(QuestionnaireContext) // null when outside Root
}

Prevention

Always wrap Questionnaire parts in <Questionnaire.Root>.
In tests, render parts inside a Root provider rather than in isolation.
Use a lint rule or wrapper component so Root-scoped parts cannot be imported bare.

When it happens

Trigger: Rendering a Root-scoped Questionnaire part (e.g. Content, Title) without a <Questionnaire.Root> ancestor; importing a part into a different React tree; conditional rendering that drops the Root but keeps the children.

Common situations: Refactoring layout and forgetting the Root; mounting a single part in isolation or in tests without a provider.

Related errors

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