Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Bootstrap 5 modal in React throws a 'backdrop' TypeError

ErrorUncaught TypeError: Cannot read properties of undefined (reading 'backdrop')

Short answer

Bootstrap's Modal reads its options from the element you pass in. If that element is null (React has not mounted it yet) or the modal instance belongs to an element React already replaced, Bootstrap has no config to read. Create or fetch the instance from a mounted ref, inside an effect or handler.

  • Applies to Bootstrap 5.3, React 19, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Log what you pass to the Modal constructor right before you create it. If it prints null or undefined, that is the cause.

    console.log(document.getElementById('myModal'))   // or log your ref.current
  2. 2Match what you see, then jump to its fix

    1. 1The log above prints null, usually because new bootstrap.Modal runs in the component body, or before the JSX has mounted.The modal element does not exist when the constructor runsFix
    2. 2The first open works, then the error appears after the component re-mounts or you navigate back to the page.An old instance is used after React replaced the elementFix

What does the error look like?

  • Uncaught TypeError: Cannot read properties of undefined (reading 'backdrop')

Cause 1 of 2

The modal element does not exist when the constructor runs

1Check

The Bootstrap docs note that getElementById returns null when the markup is missing, and the constructor expects a DOM element or a selector that matches one.

console.log(modalRef.current)   // inside useEffect, not in the render body

2Fix

Create the instance after mount. Use a ref on the modal markup, and build the Modal inside a useEffect or inside the click handler.

import { useRef, useEffect } from 'react';
import { Modal } from 'bootstrap';

function Dialog() {
  const el = useRef(null);
  const modal = useRef(null);
  useEffect(() => {
    modal.current = new Modal(el.current, { backdrop: true });
    return () => modal.current?.dispose();
  }, []);
  return <div className="modal fade" ref={el} tabIndex={-1}>...</div>;
}

3Verify

Call modal.current.show() from a button. The modal opens and the console stays clean.

modal.current.show()

Confirmed by getbootstrap.com

Did this fix it?

Cause 2 of 2

An old instance is used after React replaced the element

1Check

Bootstrap stores the instance on the DOM element. When React renders a new element, a Modal object kept from the old one no longer matches. dispose removes that stored data.

console.log(Modal.getInstance(el.current))   // null means no instance on this element

2Fix

Ask Bootstrap for the instance of the current element each time you need it, instead of keeping an old one. Dispose in the hidden.bs.modal event, not right after hide.

const instance = Modal.getOrCreateInstance(el.current);
instance.show();

3Verify

Open, close and re-mount the component twice. Each time the modal should open.

Modal.getInstance(el.current) !== null

Confirmed by getbootstrap.com

Did this fix it?

How do I stop it coming back?

  • Touch the DOM only in effects or event handlers, never in the component body.
  • Use one control path per modal: either data attributes or the JavaScript API.
  • Put modal markup at the top level of the page, because modals use position: fixed.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.