marmelab/react-admin · error · Error

useListFilterContext must be used inside a ListFilterContext

Error message

useListFilterContext must be used inside a ListFilterContextProvider

What it means

useListFilterContext reads ListFilterContext, which is only populated by ListFilterContextProvider (set up by List/useListController internals). Outside such a provider the context is undefined and the hook throws.

Source

Thrown at packages/ra-core/src/controller/list/useListFilterContext.ts:17

import { useContext } from 'react';

import { ListFilterContext, ListFilterContextValue } from './ListFilterContext';

/**
 * Hook to read the list props from the ListFilterContext.
 *
 * Must be used within a <ListFilterContextProvider>.
 *
 * @returns {ListFilterContextValue} list controller props
 *
 * @see useListController for how it is filled
 */
export const useListFilterContext = (): ListFilterContextValue => {
    const context = useContext(ListFilterContext);
    if (!context) {
        throw new Error(
            'useListFilterContext must be used inside a ListFilterContextProvider'
        );
    }
    return context;
};

View on GitHub (pinned to 051f511bb0)

Solutions

Nest the component inside a <List> page
In tests/stories, wrap with ListFilterContextProvider providing filter/setFilter
Use alternative state sources (props, store) if no list context exists

Example fix

// before
export const MyFilterButton = () => {
  const { filter } = useListFilterContext(); // throws
};
// after
// inside a List page:
<List>
  <MyFilterButton />
</List>

Defensive patterns

Strategy: try-catch

Validate before calling

const ctx = useContext(ListFilterContext);
if (!ctx) return <DefaultFilterUI />; // avoid throwing hook path

Type guard

const hasFilterContext = (): boolean => useContext(ListFilterContext) !== null;

Try / catch

try { render(<MyFilter />); } catch (e) { if (String(e).includes('useListFilterContext')) { /* wrap in ListFilterContextProvider */ } }

Prevention

Only use the hook in components under <List>
Provide ListFilterContextProvider in tests with filter/setFilter
Keep filter components colocated with list pages

When it happens

Trigger: Calling useListFilterContext in a component not nested under <List>/<ListGuesser>/a manual <ListFilterContextProvider value={...}>.

Common situations: Custom filter UI components used on non-list pages; children extracted from a List and reused elsewhere; tests rendering the component bare.

Related errors

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