Unclear documentation on the dispose method: calling it after hide

[o-alquimista]

In JavaScript, dispose method, it mentions that there is a problem calling dispose after the component is hidden, but it doesn't explain much.

While it may seem correct to use the dispose method immediately after hide(), it will lead to incorrect results. Here’s an example of the problem use:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

It's listening for the end of the transitions, so it looks correct to me. What exactly is the problem there?

I've found this possibly related issue and this one, but that's all.

[Lopesnextgen]

Hey brother,

Your interpretation is reasonable, but the documentation example is broken

Waiting for the modal's completed hidden event before calling dispose() is the correct approach. The example in the documentation contains several separate problems.

1. The event name is invalid

This:

shown.bs.hidden

is not a Bootstrap event. It appears to combine parts of two different events.

The relevant modal events are:

• shown.bs.modal: the modal has finished opening
• hidden.bs.modal: the modal has finished closing

2. The methods belong to the Modal instance

document.querySelector() returns an HTMLElement, which does not normally have Bootstrap's hide() or dispose() methods.

You need both the element and its Bootstrap instance:

const modalElement = document.querySelector('#myModal')
const modal = bootstrap.Modal.getOrCreateInstance(modalElement)

3. The listener should be registered before calling hide()

A modal with the .fade class normally completes asynchronously, so registering the listener immediately after hide() may appear to work.

However, Bootstrap executes the callback immediately when no transition is involved. In that case, hidden.bs.modal could be emitted before the next line registers the listener.

The reliable version is:

const modalElement = document.querySelector('#myModal')
const modal = bootstrap.Modal.getOrCreateInstance(modalElement)

modalElement.addEventListener('hidden.bs.modal', () => {
  modal.dispose()
}, { once: true })

modal.hide()

Using { once: true } also prevents the cleanup callback from remaining attached if another Modal instance is later created on the same element.

Why immediate disposal is unsafe

This would be unsafe:

modal.hide()
modal.dispose()

Internally, hide() queues work that still needs the Modal instance:

• finish the modal transition
• set display: none
• update ARIA attributes
• hide and remove the backdrop
• remove modal-open from the body
• restore scrollbar styles
• emit hidden.bs.modal

Meanwhile, dispose() removes the stored instance and sets its internal properties, including _element, to null.

When the pending transition callback eventually runs, it may attempt something equivalent to:

this._element.style.display = 'none'

but _element is already null. This can produce an exception and leave behind a backdrop, locked body scrolling, or other incomplete cleanup.

That is the race condition the documentation is trying to warn about.

Practical rule

• Use hide() when you only want to close the modal.
• Use dispose() when the instance is being permanently destroyed.
• If the modal is open, wait for hidden.bs.modal before disposing or removing its element.

If the modal is dynamically created, cleanup can be:

modalElement.addEventListener('hidden.bs.modal', () => {
  modal.dispose()
  modalElement.remove()
}, { once: true })

modal.hide()

So yes, the idea you inferred is correct. The documentation should use hidden.bs.modal, operate on the actual Modal instance, and register the listener before hide().

References:

• https://getbootstrap.com/docs/5.3/components/modal/#events
• https://github.com/twbs/bootstrap/blob/v5.3.8/js/src/modal.js
• https://github.com/twbs/bootstrap/blob/v5.3.8/js/src/base-component.js
• Offcanvas hide() then dispose() runs into "this._element is null" #41473