bigskysoftware / bigskysoftware/htmx

v4: Hidden document view transition produces unhandled promise rejection

Open
#3,989 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
49.4k
Forks
1.7k
Avg merge
3d 22h
Merged PRs (30d)
30

Description

## Description

With global view transitions enabled, an HTMX swap that begins while the document is hidden produces an `unhandledrejection` even though HTMX treats a skipped transition as normal.

Observed with HTMX 4.0.0 and Firefox 152:

```text
InvalidStateError: Skipped ViewTransition due to document being hidden
```

Chromium reports the same condition with different wording.

## Reproduction

1. Set `htmx.config.transitions = true`.
2. Add an HTMX request whose response is delayed briefly.
3. Trigger the request and hide/switch away from the document before the response is swapped.
4. Observe the `unhandledrejection` event when the response arrives.

The underlying DOM update still completes.

## Cause

HTMX awaits only `finished`:

```js
await document.startViewTransition(detail.task).finished;
```

The View Transitions specification requires `ready` to reject when the document is hidden, while `finished` fulfills after the update callback completes. It also notes that `ready` is created immediately and will produce an `unhandledrejection` unless handled.

The surrounding HTMX `catch` only handles rejection from `finished`, so it cannot consume the rejected `ready` promise.

Relevant source:
https://github.com/bigskysoftware/htmx/blob/v4.0.0/src/htmx.js#L2279-L2303

Relevant specification sections:
https://drafts.csswg.org/css-view-transitions-1/#dom-document-startviewtransition
https://drafts.csswg.org/css-view-transitions-1/#viewtransition-interface

## Expected behavior

A view transition skipped for normal lifecycle reasons should not emit an unhandled promise rejection. HTMX could retain the returned `ViewTransition` and attach a rejection handler to its `ready` promise before awaiting `finished`.

The same code path is present in 4.0.0-beta6, so this is not specific to the stable release.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.