marmelab/react-admin · error · Error

useListContext must be used inside a ListContextProvider

Error message

useListContext must be used inside a ListContextProvider

What it means

useListContext reads React context that only ListContextProvider (used internally by List, DataTable, etc.) provides. Without a provider, the context is undefined and the hook throws instead of returning garbage.

Source

Thrown at packages/ra-core/src/controller/list/useListContext.ts:69

 *                     </Button>
 *                 }
 *                 {page !== nbPages &&
 *                     <Button color="primary" key="next" onClick={() => setPage(page + 1)}>
 *                         Next
 *                         <ChevronRight />
 *                     </Button>
 *                 }
 *             </Toolbar>
 *     );
 * }
 */
export const useListContext = <
    RecordType extends RaRecord = any,
    ErrorType = Error,
>(): ListControllerResult<RecordType, ErrorType> => {
    const context = useContext(ListContext);
    if (!context) {
        throw new Error(
            'useListContext must be used inside a ListContextProvider'
        );
    }
    return context as ListControllerResult<RecordType, ErrorType>;
};

View on GitHub (pinned to 051f511bb0)

Solutions

Render the consuming component inside <List> or <ListContextProvider value={controllerResult}>
In tests, wrap with a ListContextProvider supplying the needed value
If only partial state is needed, use the specific hooks with their own providers, or pass props directly
Pass list state via props instead of context for detached components

Example fix

// before
export const MyWidget = () => {
  const { data } = useListContext(); // throws
  ...
};
// after
const ListPage = () => (
  <List>
    <MyWidget />
  </List>
);

Defensive patterns

Strategy: try-catch

Validate before calling

const ctx = useContext(ListContext);
if (!ctx) {
  // render fallback instead of calling the hook's throwing path
  return <FallbackList />;
}

Type guard

const inListContext = (): boolean => useContext(ListContext) !== null;

Try / catch

try { render(<MyListChild />); } catch (e) { if (String(e).includes('useListContext')) { /* wrap in ListContextProvider */ } }

Prevention

Only call useListContext in components mounted under <List> or ListContextProvider
In tests, create a renderWithListContext helper wrapping the provider
Prefer prop drilling when a component must work both inside and outside lists

When it happens

Trigger: Calling useListContext in a component rendered outside <List>, <ListContextProvider>, or <DataTable> roots — e.g. a custom page or a child that skips the provider.

Common situations: Custom row/dialog components placed outside the list; rendering list children in tests without wrapping in ListContextProvider; refactored components moved out of a List page.

Related errors

AI-assisted analysis of marmelab/react-admin@051f511bb0 (2026-08-30). Data as JSON: /api/errors/0a8854e36159d3ec. Report an issue: GitHub.