marmelab/react-admin · error · Error

The <FilterButton> component requires the <List filters> pro

Error message

The <FilterButton> component requires the <List filters> prop to be set

What it means

FilterButton toggles the filters declared on the parent list. If useFilterContext() returns nothing and no filters prop was passed, there are no filters to toggle, so react-admin throws at render time.

Source

Thrown at packages/ra-ui-materialui/src/list/filter/FilterButton.tsx:88

        showFilter,
        hideFilter,
        sort,
    } = useListContext();
    const hasFilterValues = !isEqual(filterValues, {});
    const validSavedQueries = extractValidSavedQueries(savedQueries);
    const hasSavedCurrentQuery = validSavedQueries.some(savedQuery =>
        isEqual(savedQuery.value, {
            filter: filterValues,
            sort,
            perPage,
            displayedFilters,
        })
    );
    const [open, setOpen] = useState(false);
    const anchorEl = useRef();

    if (filters === undefined) {
        throw new Error(
            'The <FilterButton> component requires the <List filters> prop to be set'
        );
    }

    const allTogglableFilters = filters.filter(
        (filterElement): filterElement is React.ReactElement => {
            return (
                React.isValidElement(filterElement) &&
                !filterElement.props.alwaysOn
            );
        }
    );

    const handleClickButton = useCallback(
        event => {
            // This prevents ghost click.
            event.preventDefault();
            setOpen(true);

View on GitHub (pinned to 051f511bb0)

Solutions

1. Provide filters: <List filters={[<SearchInput source="q" alwaysOn />]}>.
2. Pass the filters array directly to <FilterButton filters={[...]}>.
3. Remove FilterButton from the actions if the list has no filters.

Example fix

// before
<List>
  <FilterButton />
</List>
// after
<List filters={[<SearchInput source="q" alwaysOn />]}>
  <FilterButton />
</List>

const filters = useFilterContext() ?? filtersProp;
if (!filters) return null; // or render FilterButton only when filters are configured

const hasFilters = (f: unknown): f is React.ReactElement[] => Array.isArray(f) && f.length > 0;

try { render(); } catch (e) { if (String(e).includes('requires the <List filters> prop')) return null; throw e; }

When it happens

Trigger: Rendering <FilterButton /> outside a <List filters={[...]}> context without passing a filters prop, or a List rendered without the filters prop while its FilterButton is used.

Common situations: Copying a filter toolbar into a custom page, or forgetting the filters prop on <List> while keeping the default ListView actions.

Related errors

• useReferenceFieldController: missing reference prop. You mus
• useShowController requires an id prop or a route with an /:i
• useNextPrevController was called outside of a ResourceContex
• To create a new option, you must pass an onCreate function o
• <InfiniteListBase> requires either a 'render' prop or 'child

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