{"record":{"id":"8ff3a62223ceee99","repo":"heroui-inc/heroui","slug":"usecalendarorrangestate-must-be-used-within-a-cal","errorCode":null,"errorMessage":"useCalendarOrRangeState must be used within a <Calendar> or <RangeCalendar> component.","messagePattern":"useCalendarOrRangeState must be used within a <Calendar> or <RangeCalendar> component\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/react/src/components/calendar-year-picker/use-calendar-state.ts","lineNumber":17,"sourceCode":"\"use client\";\n\nimport {use} from \"react\";\nimport {CalendarStateContext} from \"react-aria-components/Calendar\";\nimport {RangeCalendarStateContext} from \"react-aria-components/RangeCalendar\";\n\n/**\n * Returns the active Calendar or RangeCalendar state from RAC context.\n * Must be used inside <Calendar> or <RangeCalendar>.\n */\nfunction useCalendarOrRangeState() {\n  const calendarState = use(CalendarStateContext);\n  const rangeCalendarState = use(RangeCalendarStateContext);\n  const state = calendarState ?? rangeCalendarState;\n\n  if (!state) {\n    throw new Error(\n      \"useCalendarOrRangeState must be used within a <Calendar> or <RangeCalendar> component.\",\n    );\n  }\n\n  return state;\n}\n\nexport {useCalendarOrRangeState};\n","sourceCodeStart":1,"sourceCodeEnd":26,"githubUrl":"https://github.com/heroui-inc/heroui/blob/7546fff8136f538a2f56a52257c621a5cd616a1d/packages/react/src/components/calendar-year-picker/use-calendar-state.ts#L1-L26","documentation":"useCalendarOrRangeState is an internal-ish hook used by CalendarYearPicker parts. It reads both the CalendarStateContext and RangeCalendarStateContext; if neither provider is found (i.e., the hook is called outside a <Calendar> or <RangeCalendar> subtree), it throws immediately. The library throws because the year picker depends on the parent calendar's state (focused date, selection) to function.","triggerScenarios":"Calling useCalendarOrRangeState() (or rendering a CalendarYearPicker part that uses it, e.g. CalendarYearPicker.Grid or Trigger) outside of a <Calendar> or <RangeCalendar> component tree; or rendering such parts in a portal/separate React root that is not a descendant of the calendar provider.","commonSituations":"Building a standalone year-picker, copying CalendarYearPicker internals into a custom component, extracting a sub-part into its own file and rendering it in isolation in a story/test, or accidental usage outside the compound component hierarchy.","solutions":["Move the component using this hook inside <Calendar>...</Calendar> or <RangeCalendar>...</RangeCalendar> so the context provider is an ancestor","If you only need the year picker UI, compose it as <Calendar><CalendarYearPicker.Trigger/><CalendarYearPicker.Grid/></Calendar> instead of standalone parts","If rendering in a portal or separate root, ensure the calendar context provider wraps that root, or pass state via props instead of context","Check that you haven't destructured the compound component incorrectly (e.g., using internals like useCalendarOrRangeState directly)"],"exampleFix":"// before\n<CalendarYearPicker.Grid /> // rendered standalone\n\n// after\n<Calendar>\n  <Calendar.YearPicker />\n</Calendar>","handlingStrategy":"validation","validationCode":"import {Calendar, RangeCalendar} from \"@heroui/react\";\n// Ensure the consumer is a descendant:\n// <Calendar> or <RangeCalendar> must wrap the component using calendar state.","typeGuard":"// Not runtime-checkable generically; structurally, only use calendar internals\n// inside components rendered as children of <Calendar>/<RangeCalendar>.\nconst isInsideCalendar = (el: HTMLElement | null) =>\n  !!el?.closest('[data-slot]'); // adjust to the calendar's data-slot value","tryCatchPattern":null,"preventionTips":["Only render calendar sub-parts as descendants of <Calendar>/<RangeCalendar>","Wrap isolated sub-component tests/stories with the full calendar provider","Avoid importing internal hooks like useCalendarOrRangeState in app code"],"tags":["react","context","calendar","compound-components","hooks"],"backgroundTag":"react-context-provider-missing","analyzedSha":"7546fff8136f538a2f56a52257c621a5cd616a1d","analyzedAt":"2026-08-28T13:15:49.959Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}