mantinedev/mantine · critical · Error

useFormContext was called outside of FormProvider context

Error message

useFormContext was called outside of FormProvider context

What it means

useFormContext is a hook that reads React context created by createFormContext(). It throws when called in a component that is not rendered inside the corresponding FormProvider, because the context value is undefined. The library throws instead of returning undefined to fail fast on invalid form usage.

Source

Thrown at packages/@mantine/form/src/FormProvider/FormProvider.tsx:22

export interface FormProviderProps<Form> {
  form: Form;
  children: React.ReactNode;
}

export function createFormContext<Values, TransformedValues = Values, Rules = any>() {
  type Form = UseFormReturnType<Values, TransformedValues, Rules>;

  const FormContext = createContext<Form | null>(null);

  function FormProvider({ form, children }: FormProviderProps<Form>) {
    return <FormContext value={form}>{children}</FormContext>;
  }

  function useFormContext() {
    const ctx = use(FormContext);
    if (!ctx) {
      throw new Error('useFormContext was called outside of FormProvider context');
    }

    return ctx;
  }

  return [FormProvider, useFormContext, useForm] as [
    React.FC<FormProviderProps<Form>>,
    () => Form,
    UseForm<Values, TransformedValues, Rules>,
  ];
}

View on GitHub (pinned to 8a284e2c2c)

Solutions

1. Wrap the component tree (including all components that call useFormContext) in the FormProvider returned from the same createFormContext() call: <FormProvider form={form}>...</FormProvider>
2. If the component can render standalone, pass the form object down as a prop instead of reading it from context
3. In tests, wrap the rendered component in the FormProvider (or a custom render helper that does so)
4. Make sure you are using the useFormContext exported from the same createFormContext module, not from a different form instance

Example fix

// before
function MyForm() {
  const form = useFormContext(); // throws
  return <input {...form.getInputProps('name')} />;
}

// after
function App() {
  const form = useForm({ initialValues: { name: '' } });
  return (
    <FormProvider form={form}>
      <MyForm />
    </FormProvider>
  );
}

import { FormProvider, useFormContext } from './form-context';

function useOptionalForm() {
  const el = useRef<HTMLDivElement>(null);
  // Context presence must be checked by the provider structure itself;
  // you can detect it before calling the hook only by static tree inspection:
  // ensure <FormProvider> is an ancestor in JSX.

// Not possible at runtime before calling the hook (hooks cannot be conditional).
// Static guard: verify the JSX tree wraps consumers in <FormProvider>.
const isInsideProvider = (node: React.ReactNode): boolean =>
  /* walk React element tree checking for FormProvider type */ true;

// Wrap the consuming component if it must render outside the provider
function SafeInput(props) {
  try {
    // hooks can't be called in try/catch — instead guard by structure:
    return <InputWithForm {...props} />;
  } catch {
    return <PlainInput {...props} />;
  }
}
// Prefer: always render inside <FormProvider> or pass form as prop.

When it happens

Trigger: Calling useFormContext() (returned from createFormContext) in a component that is not a descendant of the FormProvider component from the same createFormContext call. Also happens when nesting providers incorrectly or using useFormContext from a different createFormContext instance whose provider is not above the consumer.

Common situations: Rendering form fields outside the <FormProvider> wrapper (e.g. in a sibling component, portal root, or modal rendered outside the form tree); forgetting to wrap the component tree in FormProvider after refactoring; mixing up useFormContext from two separate createFormContext calls; testing a component in isolation without the provider.

Related errors

• [@mantine/modals] useModals hook was called outside of conte
• @mantine/core: MantineProvider was not found in component tr
• [@mantine/core] MantineProvider was not found in tree
• [@mantine/core] MantineProvider was not found in tree
• ${errorMessage}

AI-assisted analysis of mantinedev/mantine@8a284e2c2c (2026-08-28). Data as JSON: /api/errors/ec3121f10b11d284. Report an issue: GitHub.