Anyone got a good feel for the htmx accessibility story at the moment?
I'm interested in using it more, but I want to be 100% confident that I understand how to get htmx sites to work well with screen readers. I worry about things like fetching new data into a page not altering the screen reader user in the same way as refreshing a page completely would.
I'm not interested in whether or not htmx uses the correct ARIA attributes - I want to be confident that those ARIA attributes (or similar) do the right thing.
My ideal is still to use JavaScript libraries where the documentation not only describes how they work with screen readers, but is accompanied by video evidence showing the experience a screen reader user gets for different problems solved by that library.
This is one reason I created https://alpine-ajax.js.org.
A few years ago there were a lot of examples in the HTMX documentation that discouraged accessibility and progressive enhancement. Stuff like like clickable <div>s, ignored keyboard focus, lack of screen reader announcements.
There’s been some improvement latel, but I still think the library has a lot of foot guns for new web developers.
Handling ARIA attributes is out of scope for HTMX. It is your responsibility to include ARIA attributes on the HTML you return and swap/transclude.
As for handling dynamic content for screen readers, focus management is already a thing, and is in the scope of browser standards and the HTML your backend returns. As before, it's your responsibility to manage this. HTMX will neither help you nor get in your way.
HTMX merely extends hypertext functionality to its (mostly) natural conclusion. It is not a component library, or a framework for building components, or a site building framework, or...
You can use other tools to enhance and audit accessibility, but their use is orthogonal to HTMX. I think web developers in general are very used to frameworks abstracting a ton of complexity, but HTMX is not a framework so much as a standardized set of tools for specific low level problems, it is not a one stop shop.
In that case it would be great if the HTMX documentation included worked examples and guidance for how to do this.
Leaving accessibility up to the end developer feels like a genuine missed opportunity for me here. One of the great things about NOT using a JavaScript library is that you can rely on the browser's default accessibility features for forms and links. Those benefits are the thing I care most about when considering HTMX or jQuery or React or Vue or similar.
> The server will bulk-update the statuses based on the values of the checkboxes. We respond with a small toast message about the update to inform the user, and use ARIA to politely announce the update for accessibility.
If you check the Server Requests panel it also shows the responses and the ARIA attribute they include.
The key is to mark all live regions statically before doing any htmx requests, then injecting the response HTML inside those regions. Then they are announced by the screen reader. This is nothing special to htmx of course; every app needs to work the same way.
> In that case it would be great if the HTMX documentation included worked examples and guidance for how to do this.
You can refer to the WAI-ARIA standards.
> Leaving accessibility up the end developer feels like a genuine missed opportunity.
This doesn't compute for me. What would HTMX even provide? It's a set of attributes that extend the behavior of form submission to other elements and all request methods.
> HTMX or jQuery or React/Vue
These aren't the same kinds of tools. They address fundamentally different things. Handling ARIA automatically for you isn't in scope for any of them.
> > In that case it would be great if the HTMX documentation included worked examples and guidance for how to do this.
> You can refer to the WAI-ARIA standards.
Every time someone asks for concrete a11y advice for concrete situations, some joker refers them to WAI-ARIA. This is ridiculous! That document is extremely hard to parse, and it offers absolutely no guidance wrt which parts matter the most, or, say, how the various real screen readers used in the wild behave. Please stop doing this. Accessibility is hard to get right! Making people feel like they're idiots for trying is very unhelpful.
And then you get to WAI-ARIA's practical examples and they have a yellow warning intoning "not intended for production environments" and there "may be support gaps" in assistive technology: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/c...
> That document is extremely hard to parse, and it offers absolutely no guidance wrt which parts matter the most, or, say, how the various real screen readers used in the wild behave.
No, but it does enumerate what is available which is the starting point for figuring out what is relevant to your use case.
If you want tutorials or guides relevant to your particular use case you can seek those out, but to understand them you will need familiarity with the set of available attributes and where they are or are not permitted.
Many (most?) tutorials online have flagrant violations of the specification. We need better ones that actually emphasize understanding WAI-ARIA and not cowboy markup recipe books.
> Please, stop doing this.
No, I will not stop telling people to familiarize themselves with the primary reference material. Reading technical documentation and specifications relevant to a project is not an optional step.
It is not complete in the ways you describe (actually testing real screen readers is crucial), but it is absolutely essential reading to begin with.
> Reading technical documentation and specifications relevant to a project is not an optional step.
Well, I'm competent at HTML and CSS yet I never properly read the HTML or CSS specs either. Specs are generally a terrible place to learn a technology.
I simply don't understand how it's possible that the people who seem to care most about accessibility also seem to deeply, strongly believe that doing good accessibility ought to be very hard and time-consuming, and you don't deserve to call yourself a proper web dev without going through the rites. It's... not very accessible!
> Well, I'm competent at HTML and CSS yet I never properly read the HTML or CSS specs either.
I would strongly recommend you do! Most web developers are unaware of a good deal of just what all is available to them in those specs (especially HTML).
Referring to the ARIA standards doesn't help me answer the more important question: will what I'm doing work in screen readers or not?
I feel completely starved of information here. I care about accessibility. I want to build a web page where clicking on a tab refreshes a subset of that page... and I still can't find a really good guide on how to do that in a way that works in screen readers, that's accompanied by a video (ideally multiple videos, one for each common screen reader) showing the experience I can expect my users to have from that pattern.
HTMX actively encourages that pattern, so I'd love to see the project also embrace helping developers do The Right Thing with regards to the accessibility of that pattern.
> I feel completely starved of information here. I care about accessibility. I want to build a web page where clicking on a tab refreshes a subset of that page... and I still can't find a really good guide on how to do that in a way that works in screen readers, that's accompanied by a video (ideally multiple videos, one for each common screen reader) showing the experience I can expect my users to have from that pattern.
I completely agree that this is a pain point. In general, high quality documentation is lacking. I am not however convinced that this is a problem that can be automated and abstracted away. Neither am I convinced that it's one we should necessarily try to hide. It won't win me any favors but I think the issue here is simply an endemic skill and knowledge gap. Shifts in culture via higher educational curricula and stated quality attribute priorities within companies will do more good here than anything else.
Accessibility is a quality that needs to be built in from the start. The good news is that provided your HTML is sane and not a mess of class tagged DIVs, or you're building a pretty straightforward document-like navigation/content/etc site, you really only need to declare attributes to handle the places you do something unusual. The defaults are generally correct.
Much of this "unusual" behavior that needs special treatment is within custom components (e.g. a custom date selector widget with plenty of invisible divs used for layout of the calendar days can be inscrutable to a screen reader without hinting) and is the responsibility of component library or framework producers. Some issues here run deeper, like properly correlating ARIA attributes in shadow and light DOM. But that being the case, such component libraries aren't even necessarily suitable for many sites (either too complex, or make too many mismatching assumptions).
The bulk of the remaining accessibility attribute slinging that needs to happen has to do with the overall site layout (especially reactive layouts). I don't know of any framework that will handle this for you in a satisfying way for anything sufficiently sui generis.
I think the tough but true answer here is "the people building the site should have at least skimmed the WAI-ARIA standard, and be using an auditing tool, and know what to be thinking about as they design the site from the start".
Everyone needs to read this spec and then live and breathe its tenets … sure. This reminds me of the time when we fixed the footguns with C by making everyone into better developers.
That guy is asking you if replacing a part of the html with some other html alerts screen readers to the change.
It’s a reasonable question and you could share what you know about how screen readers react when this replacement happens. You could write some documentation on how to alert them, some best practices to follow.
Instead you say read the fucking manual, as if that
helps. You put on a veneer of caring for accessibility but it seems you care about the “purity” of htmx more.
Frontend frameworks often do spend a lot of time thinking about the accessibility concerns associated with client side routing, so it's not absurd to consider this question in scope for a frontend library that handles DOM updates.
Some of this will have to be bespoke work done on a per-site basis, but I'm not sure I'm comfortable with the idea of completely punting this responsibility to developers using htmx, even if it does make philosophical sense to say "this is scope creep", because ultimately users with disabilities will end up being the ones whose experience on the web is sacrificed on this altar of ideological purity.
> That guy is asking you if replacing a part of the html with some other html alerts screen readers to the change....It’s a reasonable question
Of course it is, but it's like asking if using React.js will prevent SQL injection attacks. They are orthogonal things. Making screen readers announce things is controlled by the HTML you write, not by htmx.
It's actually like asking what a database library will do to prevent SQL injection attacks. And the answer is simple - "don't do string interpolation yourself, instead use the `(?, ?)` syntax". If you use that the SQL escaping will be taken care of automatically by the library. If the database library said something idiotic like "read the spec and implement your own SQL escaping logic" it would be a dereliction of duty.
Make no mistake, a frontend library like htmx has a responsibility to not break the front end from an accessibility perspective. If existing screenreaders break when you replace HTML then the htmx approach is broken and htmx needs to address that.
Conceptually htmx is closer to Fetch API + set innerHTML than it is to a 'frontend library' like React.js. Do people complain that setting innerHTML from JavaScript breaks screen readers? Of course not, they set up aria-live regions correctly as shown in plenty of accessibility documentation. htmx can't make the decision for you what your aria-live regions are and what text should be read out when the content changes, you need to decide that yourself.
Do people go after these frameworks saying they need to handle breaking screenreaders by dynamically updating content? Of course not. Setting live regions is the responsibility of the web page creator, not the framework.
Yes, I do go after those frameworks saying they need to at the very least help their users understand what they should do. I'm disappointed by any JavaScript library or framework that doesn't provide good documented examples for this, which is almost all of them.
Being affiliated with htmx or not doesn't change basic facts about web accessibility :-D Go look at the links I posted, look for the issues people filed against the repos claiming that their dynamic content updates break screen readers. There are zero. People understand how web accessibility works and what responsibilities lie at which parts of their stack.
Now if you say that component frameworks like shadcn/ui or whatnot should implement accessible behaviours and patterns, I am 100% with you on that. But React/Vue/htmx are at a lower level, they can't decide those things for you.
"It won't win me any favors but I think the issue here is simply an endemic skill and knowledge gap."
My problem with that is that, as you can hopefully see, I am very motivated to learn how to do this... and yet I have not managed to learn it.
"Learn how to do it" only works if there are clear and obvious resources we can point people to that will help them learn what the need to learn. The ARIA spec is not that.
This also feels like an inherently solvable problem, which is why I always take any opportunity to put it in front of people that might feel incentivized to help solve it.
There was a time when I didn't know anything about web accessibility. But I learned by reading, trying out small experiments, and using a screen reader to check my work. If I can do it, you can certainly do it.
> This also feels like an inherently solvable problem
It shouldn't, especially if you don't know anything about web accessibility. It's hubris to think that something we know nothing about should already have been solved, why hasn't it? Is everyone else just an idiot? No, of course not. It's a complex and nuanced problem. Not the basics like always put an `alt` attribute in your `img` tag, those things are easy. But when you insert dynamic updates with JavaScript into the mix, it gets more complex.
The thing I was describing as a solvable problem was the lack of easily discoverable, clear tutorials - especially for the various libraries and frameworks that encourage patterns like updating small areas of a page that can cause problems.
And yes, I agree it is not the clear and obvious resource we can point people.
We DO need better "guide" format documentation, rather than dry technical reference. Nearly everything I've seen online is in very poor shape or outright wrong.
I share your feeling that it is solvable, and I also hope that people will help solve it.
But I'm sure of one thing: the people who write that documentation will be familiar with the specifications and refer to them (among other sources) while writing.
An "Accessibility Book" (like sections of the Python and Django docs, or the Rustonomicon for unsafe Rust) would be a fantastic resource and I hope someone writes it.
> I feel completely starved of information here. I care about accessibility. I want to build a web page where clicking on a tab refreshes a subset of that page... and I still can't find a really good guide on how to do that in a way that works in screen readers
More generally, I often see people calling others "lazy" for not making websites accessible, but I personally found it hard to get my head around the WCAG recommendations, and I work with designers/developers all the time that don't know how to follow the WCAG recommendations even when you point them to documents and tutorials.
It's like nobody wants to admit it's difficult, and that's not even getting into screen readers still having many inconsistencies for basic UI patterns.
There are some sites that try to document what works and doesn't in different screen readers (e.g. https://a11ysupport.io/tests/), but even then it's still not easy knowing what to do and I don't know of an authoritative up-to-date site.
> I work with designers/developers all the time that don't know how to follow the WCAG recommendations even when you point them to documents and tutorials.
> It's like nobody wants to admit it's difficult, and that's not even getting into screen readers still having many inconsistencies for basic UI patterns.
Accessibility IS hard.
It feels sometimes like nearly everyone involved thinks they'll just read a few good blog posts and know how to make sites accessible. Then the struggle is due to not having read good enough blog posts.
Everyone wants a quick "fix" to a lack of education. Nothing replaces familiarizing one's self with primary source specifications, and most crucially, spending significant time trying out real screen readers.
I think what they are trying to say is that it has very little to do with htmx or react of whatever framework. None of it can handle accessibility automagically. Its like asking if it can write html for you - its different problem and a skill. But skills in accessibility apply to all frameworks.
Pointing at the ARIA spec as a way of writing code that’ll work with all assistive tech is like pointing at the HTML and CSS specs circa 2005 and saying that following them will make your site work in all browsers.
tl;dr htmx is better than a lot of alternatives, but Simon is right, it can improve this story and it has a responsibility to do so.
As a framing device: any interactivity that is not described with HTML is interactivity that someone is responsible for making accessible (which you correctly pointed out). Unlike JS frameworks, htmx encourages the developer to solve problems with HTML first, so the inaccessible surface area that the developer has to worry about is going to be much smaller on htmx-based applications than it is with JS-based applications. That's a pretty strict win from where a lot of the industry is right now.
That having been said, I agree with you (and disagree with a lot of our defenders in the comments) that thinking about this is in-scope for htmx. In fact, I'm a firm believer that libraries are exactly where responsibility for implementing ARIA attributes live. The average web developer should not have to think about this at all—they should be able to use declarative abstractions and trust that they are annotated correctly for screen readers. This is the only system that scales, and htmx should adhere to it as much as possible.
Ideally, htmx would just add the polite notification attribute to the elements it processes, and give an easy way to customize that. I think it's basically possible to do this in a backwards-compatible way (first as an extension) that aligns with the maintenance strategy outlined in this essay. And I do think we can improve the documentation as well.
I would argue that frontend libraries like htmx and React are not the place to build in ARIA attributes patterns/behaviours. In fact, none of the Big Ones do anything specifically w.r.t. announcing changes. See https://news.ycombinator.com/item?id=42625070
What would be the appropriate place, imho, would be component frameworks that are built on top of htmx. FastHTML is an example; they already have htmx integration and they talk about server-side components. If we look at a popular one in React, this is what they do: https://blog.logrocket.com/aria-live-regions-for-javascript-...
Thinking about it in terms of dream-html[1], it might look like:
let announce msg =
p [
class_ "announcement";
Hx.swap_oob "innerHTML:.announcement";
Aria.live `polite;
] [txt "%s" msg]
(* POST /purchase *)
let purchase request =
let thank_you_fragment = ... in
Dream_html.respond (
(* Join fragments together *)
null [
thank_you_fragment;
announce "Your purchase has been successful!";
]
)
I'm thrilled to hear you're thinking about this. I really like the philosophy of the project, very happy to hear that reducing accessibility friction is a value you care about too.
Yeah, any website that uses JavaScript to load page elements needs to solve this. My hope is that a library like HTMX can help reduce the friction in implementing the best possible patterns for doing so.
See the proposed moveBefore API [1] which is meant to solve those issues at the platform level. In the meantime, htmx has their morphdom extension, which I’d say is a must when replacing any page content with interactive elements within. Aside from that one major gotcha, the main issues with htmx are the poor accessibility of the examples in the docs [2]. In particular seeing so much ARIA without the corresponding keyboard support.
I understand screenreaders have a set of standards, aria tags etc - but are the next generation of AI screenreaders (I’m sure some already use AI?) going to replace the need for these tags, and just read a page as a human would?
I'm interested in using it more, but I want to be 100% confident that I understand how to get htmx sites to work well with screen readers. I worry about things like fetching new data into a page not altering the screen reader user in the same way as refreshing a page completely would.
I'm not interested in whether or not htmx uses the correct ARIA attributes - I want to be confident that those ARIA attributes (or similar) do the right thing.
My ideal is still to use JavaScript libraries where the documentation not only describes how they work with screen readers, but is accompanied by video evidence showing the experience a screen reader user gets for different problems solved by that library.