HTMX 4: Autofocus on Web Awesome components causes swap failure during history restore

[lehoanggiap]

Problem

When a Web Awesome component (e.g., <wa-input>) has the autofocus attribute and HTMX restores a page from browser history, HTMX attempts to focus the element before the Web Awesome component is fully registered and initialized. This causes a TypeError: Cannot read properties of null (reading 'focus') error, which aborts the entire swap operation. As a result, htmx:after:swap never fires, preventing HTMX from re-initializing form attributes like hx-put, causing forms to fall back to default browser submission (GET requests).

Important Context: Web Awesome Component Registration

Web Awesome components require time to be defined/registered. According to the Web Awesome documentation on awaiting registration, components need to be awaited before they're fully functional. HTMX's autofocus handling runs before this registration completes, causing the error.

Steps to Reproduce

1. Create a page with a form containing a Web Awesome input with autofocus and open it in the browser

   <form id="testForm" hx-put="/test">
       <wa-input autofocus id="customer-input" name="name"></wa-input>
   </form>

2. Navigate to another page
3. Click browser back button to the test page at step 1
4. Submit the testForm

Expected: Form submits via HTMX PUT request, data is updated

Actual: Form submits as regular browser form (GET request with query parameters)

Root Cause

HTMX's autofocus handling runs during the swap process (in htmx:before:swap). When it encounters a Web Awesome component with autofocus, it tries to call .focus() on the element. However Web Awesome components need time to register: According to Web Awesome documentation, components must be awaited before they're fully functional

Suggestion

I think we should remove the handleAutoFocus logic during swapping. The code looks for an element with autofocus and explicitly calls focus() on it, which is redundant—elements with autofocus will automatically receive focus without needing an explicit focus() call.

[MichaelWest22]

The issue is that we have to call focus() manually because browsers only respect autofocus attributes on inputs on full page loads and it is ignored elsewhere. Web Awesome web components may have custom javascript code to manually call focus on their internal input every time a new component is registered even after page load.

htmx4 already has code to only call focus() when it is defined and it seems in your case the web component has implemented a focus custom function already but if it is called to early before the light/shadow dom input element exists this triggers a bug in the wa-input component where it has this code:

/** Sets focus on the input. */
focus(options?: FocusOptions) {
  this.input.focus(options);
}

This focus function in web awsome should handle input not yet being defined but it is just calling focus on the null value here. So ideally this code should be this.input?.focus(options); so that it handles early focus attempts without errors and then its autofocus on create custom code would re-trigger the focus for you.

The only fix we could possibly do in htmx would be having to add a try catch around .focus() call to eat the error the web component is throwing us.

But there is a much simpler solution right now which is to just set htmx.config.history to 'reload' which will make htmx history restore work as a proper browser full page load avoiding all the issues with trying to partially update the page during history navigation.

[lehoanggiap]

The issue is that we have to call focus() manually because browsers only respect autofocus attributes on inputs on full page loads and it is ignored elsewhere. Web Awesome web components may have custom javascript code to manually call focus on their internal input every time a new component is registered even after page load.

htmx4 already has code to only call focus() when it is defined and it seems in your case the web component has implemented a focus custom function already but if it is called to early before the light/shadow dom input element exists this triggers a bug in the wa-input component where it has this code:

/** Sets focus on the input. */
focus(options?: FocusOptions) {
  this.input.focus(options);
}

This focus function in web awsome should handle input not yet being defined but it is just calling focus on the null value here. So ideally this code should be this.input?.focus(options); so that it handles early focus attempts without errors and then its autofocus on create custom code would re-trigger the focus for you.

The only fix we could possibly do in htmx would be having to add a try catch around .focus() call to eat the error the web component is throwing us.

But there is a much simpler solution right now which is to just set htmx.config.history to 'reload' which will make htmx history restore work as a proper browser full page load avoiding all the issues with trying to partially update the page during history navigation.

Ok thanks @MichaelWest22

[MichaelWest22]

One other option to work around this issue could be to use the htmx:after:settle and htmx:after:swap events to temporarily remove and then replace the autofocus element during the autofocus processing window to disable it for web components only.

//==========================================================
// autofocus-delay.js
//
// An extension to delay autofocus until after settle
// to allow Web Components time to initialize.
//==========================================================
(function () {

    function isWebComponent(elt) {
        return elt.tagName.includes('-');
    }

    htmx.registerExtension("autofocus-delay", {
        htmx_after_settle: (elt, detail) => {
            // Find all autofocus elements in newContent and change to noautofocus
            for (const contentElt of detail.newContent) {
                if (contentElt.nodeType === Node.ELEMENT_NODE) {
                    // Check the element itself
                    if (contentElt.hasAttribute('autofocus') && isWebComponent(contentElt)) {
                        contentElt.removeAttribute('autofocus');
                        contentElt.setAttribute('noautofocus', '');
                    }
                    // Check descendants
                    for (const autofocusElt of contentElt.querySelectorAll('[autofocus]')) {
                        if (isWebComponent(autofocusElt)) {
                            autofocusElt.removeAttribute('autofocus');
                            autofocusElt.setAttribute('noautofocus', '');
                        }
                    }
                }
            }
        },
        htmx_after_swap: (elt, detail) => {
            // Find all noautofocus elements in document and change back to autofocus
            for (const noautofocusElt of document.querySelectorAll('[noautofocus]')) {
                noautofocusElt.removeAttribute('noautofocus');
                noautofocusElt.setAttribute('autofocus', '');
            }
        }
    })

})()

are you able to test this simple extension with the latest htmx4 alpha that just released?

[lehoanggiap]

Thanks @MichaelWest22 for your support. After reading this more carefully, I think that even if Web Awesome changes to use this.input?.focus(options), it would only work around the issue—similar to adding a try/catch in htmx 4—rather than truly solving it.

wa-input relies on the native HTML autofocus attribute, so there aren’t any methods that explicitly call focus() after the component is created. Because of this, asking Web Awesome to change the implementation to this.input?.focus(options) would only suppress the issue caused by calling focus() too early on an undefined element—and they may reasonably reject that approach.

I think customElements.whenDefined() could help here. For custom elements, could we simply wait for the element to be defined and then call focus() on it? Do you think that approach would work?

https://webawesome.com/docs/usage

https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/whenDefined

[MichaelWest22]

The issue here is that autofocus is only valid on an input/textbox/button and its use here is non standard which is why htmx and wa-input are tripping us up.

I think the try fetch or fixing web awsome so the function is always safe to call would work fine as the autofocus is not really doing anything native and really should have been wa-autofocus or similar as it only triggers on web component load and not page load time. So if htmx tries before it is loaded and safe fails doing nothing then later the web component will load and init and the component code will do a focus as expected. This is why the workaround I posted above for a js htmx extension should solve the problem. Htmx is designed to be highly extensible via events and extension hooks and using these allows fine grained custom behaviour without adding every custom feature to htmx core

[MichaelWest22]

Looks like a better fix for this found by HanY2B in #3622 that should also work with web awesome by just changing the sl- to wa-

[jason-kane]

I was experiencing a very similar issue (same error message) with htmx+webawesome and can confirm the patch in #3622 (comment) (with sl- changed to wa-) appears to have resolved the problem for me.