heroui-inc/heroui · error · Error

CalendarYearPicker components must be used within <CalendarY

Error message

CalendarYearPicker components must be used within <CalendarYearPicker.Grid>.

What it means

CalendarYearPicker.Grid supplies a grid context containing the years list, selection/focus state, and slot styles. Any CalendarYearPicker sub-part that consumes this context (via useCalendarYearPickerGridContext) throws when rendered outside a <CalendarYearPicker.Grid>, because the year data it renders comes from that provider.

Source

Thrown at packages/react/src/components/calendar-year-picker/calendar-year-picker.tsx:261

interface CalendarYearPickerGridContextValue {
  slots: ReturnType<typeof calendarYearPickerVariants>;
  isYearPickerOpen: boolean;
  activeYear: number;
  focusedYear: number;
  years: number[];
  getFormattedYear: (year: number) => string;
  selectYear: (year: number) => void;
  setActiveYear: (year: number) => void;
}

const CalendarYearPickerGridContext =
  React.createContext<CalendarYearPickerGridContextValue | null>(null);

function useCalendarYearPickerGridContext(): CalendarYearPickerGridContextValue {
  const context = React.use(CalendarYearPickerGridContext);

  if (!context) {
    throw new Error("CalendarYearPicker components must be used within <CalendarYearPicker.Grid>.");
  }

  return context;
}

const CalendarYearPickerGrid = <E extends keyof React.JSX.IntrinsicElements = "div">({
  children,
  className,
  format,
  onKeyDown,
  visibleYears: visibleYearsProp,
  ...props
}: CalendarYearPickerGridProps<E> &
  Omit<React.JSX.IntrinsicElements[E], keyof CalendarYearPickerGridProps<E>>) => {
  const {calendarGridSlot, calendarRef, isYearPickerOpen, setIsYearPickerOpen} = useYearPicker();
  const state = useCalendarOrRangeState();
  const gridRef = React.useRef<HTMLDivElement>(null);

View on GitHub (pinned to 7546fff813)

Solutions

1. Place the component inside <CalendarYearPicker.Grid>
2. If building a fully custom grid, re-implement the year rendering with your own data instead of consuming the grid context
3. Verify nesting against the official stories for CalendarYearPicker

Example fix

// before
<CalendarYearPicker>
  <CalendarYearPicker.YearCell year={2026} />
</CalendarYearPicker>

// after
<CalendarYearPicker>
  <CalendarYearPicker.Grid>
    <CalendarYearPicker.YearCell year={2026} />
  </CalendarYearPicker.Grid>
</CalendarYearPicker>

// Always nest grid children under:
// <CalendarYearPicker.Grid><YourGridChild/></CalendarYearPicker.Grid>

When it happens

Trigger: Rendering a grid child (a year cell or anything calling useCalendarYearPickerGridContext) outside <CalendarYearPicker.Grid>, e.g. directly under CalendarYearPicker or Calendar.

Common situations: Custom grid layouts that replace Grid but keep its children; stories/tests rendering a year cell in isolation; incorrect nesting after refactoring compound parts.

Related errors

• useCalendarOrRangeState must be used within a <Calendar> or
• useYearPicker must be used within a <Calendar> or <RangeCale
• CalendarYearPicker trigger components must be used within <C
• Ref was not connected to DOM element returned by custom `ren

AI-assisted analysis of heroui-inc/heroui@7546fff813 (2026-08-28). Data as JSON: /api/errors/1adaf21b87727cd1. Report an issue: GitHub.