htmx accessibility gaps: data and recommendations
A look at available data, known gotchas, and how to address the gaps
Every few months I’m asked about possible accessibility issues with a UI built with htmx. It’s super popular in the Django world, so felt worthwhile to take the time to dig deeper! Time to spell out where htmx shines, and where it falls short.
TL;DR;
htmx has a mixed track-record. It can be made to work well, but the official accessibility docs don’t tell a good story about it, tend to oversimplify it as "just use HTML and it’s accessible". And lots of tutorials and examples are poorly implemented, which seems to show in scoring real-world sites.
Practically – simple htmx-powered interfaces can be made accessible. But go beyond the basics and you’ll likely find yourself reinventing the wheel without much support, or have to complement htmx with a UI components library.
What the data says
The HTTP Archive Tech Report tracks the median accessibility score of lots of technologies, including htmx and React. Here’s what the data looks like over the three years where htmx detection has been available:
I’m not clear where that htmx dip comes from. Perhaps adoption moving from early adopters / web artisans, to more mainstream uses where projects care less about accessibility? Perhaps a change in the weight given to accessibility checks that htmx-powered sites might often fail? The inflection point was November 2024. Since then, on average, htmx sites clearly score worse on accessibility than the ones built with React. And they score worse than the average across the dataset.
You may be wondering why React might fare so well. I would argue it’s because of tooling. Things like accessibility-focused linting rules, Axe integrations that can be used in unit tests, that few other UI development frameworks have. There might also be something to say about the maturity of React UI components, where lots of UI patterns have many implementations intended for third-party reuse, that have been battle-tested for accessibility. For example, the React Spectrum date picker is way more accessible than browsers’ native date picker (sob 😭, that’ll be for another article).
In the Django ecosystem
The above data was a surprise to me, so I thought I’d dig deeper and look at the Django ecosystem specifically, where htmx is very popular. Here are the average scores as a "point in time" snapshot, from April 2025, comparing 500 htmx-powered sites in the Django ecosystem with 1800 React-powered sites, among 16000 Django sites in total:
The trend’s reversed! The Django web isn’t very accessible to start with, with the framework largely leaving anything front-end up to its users. I’m not clear what to make of those numbers, but – there is more data!
htmx accessibility gaps and wins
Since we track the prevalence of specific accessibility issues in the Django web, we can look at where htmx sites fare much worse, or much better, than the average Django site. Here’s the specific Lighthouse checks where the 500 htmx-powered Django sites score significantly worse, and significantly better, than the bigger set of 16000 Django sites:
Scoring worse:
- link-name means links lacking descriptive text. A common issue on the web, but surprisingly way more prevalent on htmx sites.
- heading-order means headings that are not in a logical sequence of levels. That one’s less surprising as I’ve definitely seen this done wrong in the htmx docs.
- aria-allowed-role means some HTML elements are forced to an incompatible ARIA role. Another example of anti-patterns in the htmx docs.
See the official Progress Bar example which clearly demonstrates how to fail those last two checks:
<div hx-trigger="done" hx-get="/job" hx-swap="outerHTML" hx-target="this"> <!-- h3 cannot have the status role -- > <!-- h3 will be the wrong level if there is no preceding h2 -- > <!-- TBC: the status role might not do anything when the whole element is swapped? -- > <h3 role="status" id="pblabel" tabindex="-1" autofocus>Complete</h3> <!-- […] -- > </div>
Scoring better:
- aria-hidden-focus means elements that are hidden from assistive technologies, but still focusable. Great to see htmx sites doing better than average at this!
- button-name is equivalent to link-name but for buttons. I’m not clear why this would be so different to links, possibly a tutorial or copy-pasted htmx example that’s using links incorrectly.
- aria-deprecated-role is another example of the importance of well-curated examples and tutorials.
Those findings are interesting but the sample size isn’t big, and it’s hard to tell how much those issues might be caused by the htmx implementations or just happen to be present regardless. So now, time to look at the docs and examples in more depth, see where those gaps might come from. And how to avoid them on specific projects.
Recommendations
Accessibility gets a mention in the htmx docs as part of Progressive Enhancement. This is a bit light on details for my liking, and I think oversimplifies what it means to build accessible UIs. Those oversimplifications are common in online htmx resources. I’d phrase them as:
- ❌ Simple HTML is all you need. That’s true – except when your UI becomes complex enough that it’s not.
- ❌ The least JavaScript the better. Also somewhat true – except when it leads to leaving out essential accessibility considerations.
This is examplified when comparing official htmx examples and common patterns, with the ARIA Authoring Practices Guide (APG) from W3C. This guide clearly documents how to implement common UI patterns in an accessible way, and in particular the degree to which ARIA attributes and JavaScript event processing are needed to build accessible UIs.
So this is what’s most important to be aware of when adopting htmx. If there is interactivity to implement, there’s usually more to do than is showcased in the docs and examples. That’s not a dealbreaker, but certainly a missed opportunity for the docs not to be demonstrating those patterns implemented to the fullest extent.
This has been flagged already, Review/fix examples for accessibility #a11y #1431
Major implementation gotchas
Reviewing htmx capabilities in more depth, there are two big accessibility gotchas in htmx that are worth highlighting:
- Lost UI state when replacing interactive elements.
- hx-boost replacing page content without a reload, and without managing screen readers’ position.
In both cases, there are workarounds: don’t use the problematic framework feature, or carefully implement those features to avoid the gotchas. It’s ok for frameworks to have challenges like this, but you’d want them addressed more explicitly in the docs if possible.
My personal recommendation is to avoid hx-boost altogether, and avoid replacing interactive elements with htmx. And when that’s not an option, there is a need to carefully review how much of those components’ local UI state might be lost (focus in particular). Use hx-preserve and possibly morphdom to preserve that local state when replacing elements.
Missed opportunities
The "HTML-first" fundamentals are strong despite those implementation gotchas. But there are plenty of other ways in which htmx could further guide its users towards sensible (accessible) patterns. Naming just a few, there is a clear need to:
- Update the examples to meet accessibility requirements.
- Guide htmx users on how to reuse their own components, or an ecosystem of components. To avoid reinventing the wheel on basic UI patterns.
- Suggest tools or techniques people could use to test their UI.
For all three points, there’s a case to be made that htmx focuses on the mechanisms to make those UIs happen rather than the actual UIs. The "back of the front-end" so to speak. However the lack of guidance on those points just leads to developers reinventing the wheel, trying to implement complex components with a library that’s not designed for that.
A good example of this would be the Tabs pattern from the official docs. Which would probably need an extra 30-50 lines of inline JS (💥) to fully implement the Tabs guidance from the ARIA APG. But then good luck testing that!
What to do for your project
Wrapping it up – chances are your project’s usage of htmx is simple enough that it might work great without too much special consideration of accessibility! But if you find yourself messing with ARIA role attributes or implementing lots of interactivity, consider whether you could use a dedicated UI component or library, rather than re-implementing one with htmx. And if you roll it out yourself, review available docs on ARIA to understand which existing patterns you could reuse and re-implement, rather than creating a new one.
And if unsure – the best you can do is to invest into accessibility checks, manual or automated! For Wagtail sites, our automated built-in accessibility checker is based on the Axe checker. And for manual tests, check out how we conducted our recent Wagtail.org website audit. Whether for htmx itself or individual projects, doing this type of QA is probably where there is the most room for improvements.
