Bootstrap 5 modal in React throws a 'backdrop' TypeError
Uncaught 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.
Fix it fast
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.current2Match what you see, then jump to its fix
- 1
The 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
The 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
- 1
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 body2Fix
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
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 element2Fix
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) !== nullConfirmed by getbootstrap.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fixWeb apps
Axios returns 401 from a React app but the login works elsewhere
Error: Request failed with status code 401
A 401 means the server received the request without valid credentials.
3 causes, each with a fixWeb apps
An axios call never finishes when the API server stops answering
code: 'ECONNABORTED'
Axios has no timeout unless you give it one: the default is 0, which means wait forever.
3 causes, each with a fix