hx-indicator default styles do not work for screen reader users

[thibaudcolas]

The htmx-indicator default styles rely on opacity only. Because of this, indicator elements are only visually hidden. It still appears in the accessibility tree for screen reader users. And for hover / focus if that indicator was interactive.

Here’s a recording of VoiceOver macOS in Safari demonstrating the issue on the Cascading Selects example (though note due to the demo site’s "instant" server responses, the indicator is effectively useless there).

hx-indicator.opacity.mp4

---

The best fix is probably to either add, or switch to the visibility property, which preserves layout like opacity but also removes elements from the accessibility tree.

Additionally, worth noting those <img> elements are missing an alt attribute. That attribute is never optional, and will make it so screen reader users aren’t told the image’s file name or URL, which is pretty meaningless to them (related: #1431).

[MichaelWest22]

I think one of the core purposes of the built in simple default CSS htmx-indictors is to allow basic fade in/out transitions so the indicators are less jarring. visibility property alone does not support this at all and combining visibility with opacity does create a much more complicated style definition where you have to sequence and chain the two types for both fade in and fade out I think.

The default styles should ideally be turned off using htmx.config.includeIndicatorStyles=false config item so that the application can include your own custom css file with the styles that work with your application and avoid using inline style tags which cause CSP security warnings. see #2832

Would be good to have better documentation and examples on how to setup best practice css for htmx.

[MichaelWest22]

found the last time it was updated was in #1227 where the indicator code was changed so that the transition was only on the visible class case so the base class hides the content during initial page load and you don't get a flash of un-styled or partially styled content on some page load situations.

when this went though it went from:

    .htmx-indicator{opacity:0;transition: opacity 200ms ease-in;}
    .htmx-request .htmx-indicator{opacity:1}
    .htmx-request.htmx-indicator{opacity:1}

to:

    .htmx-indicator{opacity:0}
    .htmx-request .htmx-indicator{opacity:1; transition: opacity 200ms ease-in;}
    .htmx-request.htmx-indicator{opacity:1; transition: opacity 200ms ease-in;}

But the documentaion in https://htmx.org/attributes/hx-indicator/ where examples of use cases was not updated to reflect the default indicator style change and has a 500ms figure as well.

The impact of this change 2 years ago was that it no longer shows any transition when it is added but it also disabled the transition that happens when the request finishes so it now fades in nicely at the start of the request but then vanishes instantly when the request finishes.

I don't think we can really fix the fade out transition without bringing back the flashes when using features like hx-location as all the fixes for this I can find are too complex or not practical for htmx if done the generic way htmx does things with classes.

changing it to:

.htmx-indicator {
  opacity: 0;
  visibility: hidden;
}
.htmx-request .htmx-indicator,
.htmx-request.htmx-indicator {
  opacity: 1;
  visibility: visible;
  transition: opacity 200ms ease-in;
}

I think would give us the same as the current htmx behaviour except it would work properly with screen readers. But it would keep the current limitation that fade out is instant. Would also need to update the https://htmx.org/attributes/hx-indicator/ documentation to match if we did make such a change.

Also this hx-indicator documentation it shows the intention is the users can make their own versions of the indicator css config with their own names and apply their custom class instead. There is an example of how to do this with display:none instead as an alternative option and this option already supports screen readers well. So it may be possible to instead expand the documentation in this page to give users the option to include alternative transitions that support better accessibility if required

[thibaudcolas]

@MichaelWest22 thank you for taking a look!

combining visibility with opacity does create a much more complicated style definition where you have to sequence and chain the two types for both fade in and fade out I think.

As far as I know, no? Or it depends on the easing function. visibility’s expected switching between hidden and visible is well specced. Not sure how well-implemented in browsers.

instead expand the documentation in this page to give users the option to include alternative transitions that support better accessibility if required

I’d have a hard time imagining a project where such basic degree of support for screen readers isn’t required. hx-indicator is documented as "This can be used to show spinners or progress indicators while the request is in flight.". It’s clearly not doing that currently in the default configuration, as the indicator is always-on for screen reader users.

The fact there’s an animation is completely undocumented, so I don’t think many people would care that fade-out is instant. So to me the option that’s "same as the current htmx behaviour except it would work properly with screen readers" seems pretty good.

[MichaelWest22]

Added a quick possible PR for this

[thibaudcolas]

Seems to me this is fixed by #3361. Nice one!