`useHeaderContext` must be used within an `AppHeader` or `Ap

Error message

`useHeaderContext` must be used within an `AppHeader` or `AppFooter` component.

What it means

`useHeaderContext` is a Preact context hook that reads the header context provided by `<table.AppHeader>` or `<table.AppFooter>`. The library throws this error when the hook is called and the context value is undefined, i.e. no AppHeader/AppFooter provider is above it in the component tree. This fail-fast behavior prevents operating on a null header and producing confusing downstream errors.

Source

Thrown at packages/preact-table/src/createTableHookContexts.tsx:149

      )
    }

    return cell as unknown as Cell<TFeatures, any, TValue>
  }

  /**
   * Access the header instance from within an `AppHeader` or `AppFooter` wrapper
   * bound to these scoped contexts.
   */
  function useHeaderContext<TValue extends CellData = CellData>(): Header<
    TFeatures,
    any,
    TValue
  > {
    const header = useContext(headerContext)

    if (!header) {
      throw new Error(
        '`useHeaderContext` must be used within an `AppHeader` or `AppFooter` component.',
      )
    }

    return header as unknown as Header<TFeatures, any, TValue>
  }

  return {
    // Re-typed without `| null` so they drop straight into `createTableHook`'s
    // `tableContext`/`cellContext`/`headerContext` options.
    tableContext: tableContext as unknown as Context<PreactTable<any, any>>,
    cellContext: cellContext as unknown as Context<Cell<any, any, any>>,
    headerContext: headerContext as unknown as Context<Header<any, any, any>>,
    useTableContext,
    useCellContext,
    useHeaderContext,
  }
}

View on GitHub (pinned to d01c01bedb)

Solutions

Wrap the component (or its usage site) with `<table.AppHeader>` or `<table.AppFooter>` so the header context is provided above it.
Move the component call site into the render children of AppHeader/AppFooter.
Verify only one copy/version of the table package is installed (npm ls / dedupe) so the context module identity matches.
If the component may run outside a header, fall back gracefully instead: read the raw context with `useContext` and handle null.

Example fix

// before
function MySortIndicator() {
  const header = useHeaderContext()
  return <span>{header.column.getIsSorted()}</span>
}
render(<MySortIndicator />, root)

// after
render(
  <table.AppHeader header={header}>
    <MySortIndicator />
  </table.AppHeader>,
  root
)

Defensive patterns

Strategy: validation

Validate before calling

import { useContext } from 'preact'
import { headerContext } from '@your-scope/preact-table'

function useSafeHeader() {
  const header = useContext(headerContext)
  if (!header) {
    console.error('useHeaderContext requires <table.AppHeader> or <table.AppFooter> above this component')
  }
  return header
}

Type guard

function hasHeader<T>(h: T | null | undefined): h is T {
  return h != null
}

Try / catch

try {
  const header = useHeaderContext()
  // use header
} catch (err) {
  if (err instanceof Error && err.message.includes('useHeaderContext')) {
    return null // render placeholder outside AppHeader/AppFooter
  }
  throw err
}

Prevention

Always render context-consuming components as children of table.AppHeader/table.AppFooter.
Create a small wrapper component that pairs provider + consumer and use it everywhere.
Check package.json / lockfile for duplicate table package versions.
In tests, use a mount helper that includes the required providers.

When it happens

Trigger: Calling `useHeaderContext()` inside a custom component that is rendered outside of (or as a sibling to) `<table.AppHeader>`/`<table.AppFooter>`, or having a second copy of the preact-table package installed so two different context objects exist.

Common situations: Developers build a custom header cell component and render it in a plain element instead of inside AppHeader/AppFooter; or render the component in a portal/other root without the provider; or have duplicate package versions in node_modules breaking context identity.

Related errors

AI-assisted analysis of TanStack/table@d01c01bedb (2026-08-28). Data as JSON: /api/errors/72847691631351c5. Report an issue: GitHub.