Discourse with a screen reader

Hey folks,

Not sure if this is known or tracked anywhere. If so, I’d welcome links. But, while it is improving, the experience of using Discourse with a screen reader has a few challenges that I wanted to document.

I’m a screen reader user, and wanted to set up a self-hosted instance mostly targeted at blind users. I normally don’t recommend Discourse because of accessibility issues, but you’re making self-hosting with the features I want very easy, so it makes me sad that accessibility isn’t quite there. Here are some of the challenges I’m facing:

  • The dropdowns that report to my screen reader as HTML <select/>s are almost entirely broken. They do expand via normal keyboard conventions, but that’s about where the accessibility ends. The challenges began when I had to select a language during setup. I’m not immediately sure if English: US was defaulted, but when I went to investigate, I’d managed to set the language to Spanish and had a hard time getting it back. I eventually found the list with my screen reader and managed to correct it. But just about every dropdown is broken. I don’t want to say “every” in case there’s one on some far-flung corner of the interface that works, but every one I’ve tried doesn’t work at all. :frowning:
  • I can’t find a way to the admin interface without navigating directly. The setup screens told me it was under the gear icon, but I can’t find a textual representation of what the gear icon might be, nor do any of the keyboard-accessible controls I’ve found seem to ultimately link to an admin interface. For now I’m just hitting /admin, but this makes me wonder what tools I may not be discovering because I can’t find this gear.
  • Related to the settings dropdown, I can’t use the dropdowns/selects at the top of category lists to navigate to the lists of categories. I know about the Categories link, which is what I generally use. But it’d be nice if those selectors worked.
  • Whenever I don’t sign up for a Discourse, I’m told that I should in part because the forum remembers where I stopped reading. This has never worked for me with a screen reader. How is it supposed to work? Should clicking the link move focus to whichever post I read last?
  • And not related to my site, but the modal signup experience here had some challenges. I tried signing up by email, but your instance rejected my .info email address which I’ve used for nearly 17 years and which worked fine on my own. I then signed up via Google, but the modal I was given on return posed some challenges:
    • It didn’t grab keyboard focus, so I had to hunt it down and interact with it myself.
    • While I was trying to do that, the infinitely scrolling topic list was adding new topics in and making it more difficult for focus to actually reach the dialog. I don’t remember how exactly I managed to move quicker than the topics appeared–haven’t had my coffee yet–but I’m here. :slight_smile:

So, a few questions:

  • I really want to stick with Discourse if I can. How much of this stuff can I change on my own site? In particular:
    • Can I get rid of the category list selectors, so users have to interact with the category list link for now?
    • Can I get rid of the category selector on new topic pages, so users have to first enter the category they want to post in, and can’t accidentally make uncategorized posts or otherwise get confused?
    • Can I do both in a way that makes upgrading easy? I’d rather not edit stock templates and fork the project if I don’t have to, nor do I necessarily want an entirely new theme.
  • Is this work being tracked anywhere, and is anyone dedicated to taking it on? Discourse forums are eating the internet. Everywhere I turn, the projects or communities I spend time in are adopting them. Hell, as a blind user, I want to run Discourse because, again, you make this so easy. I just don’t want accessibility of such a crucial tool to either be an afterthought, or to perpetually play catchup with new development.

Thanks for reading.


That’s a thoughtful post @nolan. I’m sure other teams members will weigh in on your questions, but can you share your set up so that a developer can try to reproduce the issues you are running into? I.e. which OS, which screen reader, and so on.


Windows 10, NVDA screen reader. Though, to put it delicately, it’s broken enough that it likely won’t work well anywhere, so just about any combination of OS/screen reader will likely hit this.


Thanks for the feedback! We know we’re not there yet with accessibility and have been working on it more lately. At the end of 2020 we had a third-party accessibility audit done for the most important non-admin pages of Discourse and have started working through the high-priority issues over the past couple of weeks.

Now that you mention it, I can understand why finding the admin menu would be difficult. The link for the menu sits within one of the primary header menus… the aria-label is “go to another topic list or category”… which definitely doesn’t make it clear there are a couple admin links within.

Regarding the message that says Discourse remembers where you left off… the expected behavior is that when you enter the topic, you skip to where you left off reading. I just tried to navigate this with the keyboard and can confirm that it’s not putting focus in the correct place.

Many of our dropdowns are a custom implementation, and that’s one of the areas that have been pointed out to us for accessibility improvement. We’re also aware of the fact that our modals don’t trap focus, which leads to difficult-to-reach content, particularly on pages with infinite scrolling as you experienced.

Regarding your questions about sticking with Discourse… everything you listed is possible; it would amount to a few lines of CSS to hide those elements. That CSS would have to be in a theme, but it could exist within a theme component, which can be added on to any existing theme (so you wouldn’t have to change your primary theme). Themes are much better for the upgrade process, as they exist on top of Discourse… editing templates or forking as you mentioned makes updating very difficult.

We tag reports of accessibility issues here on Meta with an #accessibility tag so they’re easier to find in one place… but that said, the third-party accessibility report and subsequent work I mentioned earlier aren’t being tracked publicly.

Really appreciate the feedback here, especially considering that it took additional effort to post it. I hope over the course of the next few months Discourse becomes much easier for you to use.


I got a question in a Fediverse discussion by Robert Kingett with a visual disability, and “Accessibility accelerationist” on his profile. The question was:

How are you making social Hub accessible to screen readers and other Disabled people? Seizures, ETC.

Since SocialHub runs Discourse, and the question related to accessability issues here, I offered to copy this thread as a Markdown doc in a Github Gist. So here it is and can be used for other people with visual impairment: https://gist.github.com/aschrijver/bb7e904aa0b3218fa03127c516273a6f


Also, if this hasn’t been raised, I’d like to flag it as a way for some quick accessibility wins:

Screen readers make good use of many of HTML 5’s semantic tags. Not only can I navigate between them efficiently, but they’ll also speak the type of content I’m currently in.

It’d be nice if posts in an <article/> with the header and footer in <header/> and <footer/> elements, respectively. If swapping out elements won’t work, using role attributes appropriately conveys the same meaning.

Right now it’s challenging to read long threads. After the first post, I have to scroll past the section with recommended topics and such. Then I’m reading subsequent posts linearly, with no way to skip past the same headers I’ve heard a million times with nothing different other than the date, or the footer with the same message controls. There are certainly advanced ARIA tweaks that’d make things even better, but swapping out the tags or using roles would be a low-effort fix with lots of benefit IMO.



I’ve got an update in our review queue that will add a few pieces of ARIA markup to topic pages. According to spec it seems to make sense to markup the controls under posts and at the bottom of the page with the toolbar role.

We also have a topic timeline toolbar area that serves as a scrollbar (I’ve now given it a scrollbar role) and also contains “jump to first post” and “jump to last post” buttons (which I’ve added descriptions to)…

These changes should be available with Discourse updates next week.


Neat, looking forward to it!

This may go without saying but I’ll do so anyway. Note that it isn’t enough to just slap ARIA on these controls and call it a day. In other words, marking those areas up as toolbars without following the toolbar pattern is probably worse than leaving the role off entirely. If I land on a toolbar, I’d expect it to behave in ways it doesn’t automatically just by adding the role. Just want to be clear about that, since a common mistake I see when adding accessibility is adding these roles, but not adding the associated keyboard behaviors. Then I’m landing on bunches of controls that don’t behave how I expect, and constantly struggling with those expectations is worse than not having them to begin with.

Hope that makes sense. Happy to answer additional questions.


Hi Chris, the scrollbar role might not be exactly what you want here. We’ll have to see this in action, but so far, I have not actually seen it used this way. it is more something like a range element in HTML5 that represents a relative scrolling position of a container. The “Go to first post” and “Go to last post” items are mere buttons that may scroll the view, yes, but I don’t think these buttons are appropriate as content for a scroll bar container, which is required to get aria-value* attributes.

P.S. In the VS Code community, I am known as the ARIA role guru. I don#t know what exactly got me that reputation, but I am known for being picky about roles. They can do more harm than good, so this particular change might have to be reverted. I am almost certain it will.


Out of curiosity, do you folks have anyone with an accessibility focus on the team? I’m excited about the recent accessibility audit and the planned upcoming changes, but Discourse powers enough of the internet that there should probably be someone with in-the-trenches experience working alongside and advising these changes. It’s super easy to get things wrong and to unintentionally make things worse.

As an example, Slack claims to have an accessibility focus, and they do try using ARIA, but their attempts seem to have rendered the chat area entirely inaccessible via my screen reader. Or if it is accessible, I with a couple decades’ experience can’t figure it out. :slight_smile: I don’t want to see Discourse take that path unintentionally.

Anyhow, I do this and similar for a living and am available. I also use a number of Discourse forums, so accessibility I can count on would be a tangible quality-of-life improvement for me. :slight_smile: Happy to talk more with anyone who is interested.


@MarcoZehe for our timeline control, I was a little on the fence on whether to go with the scrollbar role or the slider role. I decided on the scrollbar role because the control does scroll the page and it does sound like it fits the description given by the W3C:

A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area.

That said, it is a somewhat unique control we’ve built… it both scrolls the page and displays where you are within the current range of posts (so for example it will show you’re currently on post 6 of 12). It’s possible that there’s not a great way to mark it up for screen readers at all, and might be better off hidden… as normal page scrolling works as you’d expect without it. I’d like to give it a try and see what you think of it in action, and if it doesn’t work we can revert.

To answer your question @nolan, I’ve taken on the responsibility of organizing accessibility recommendations and getting our audit done, but most of my previous experience with accessibility comes from implementing specifications defined by others. We don’t have a dedicated expert working on accessibility full-time, as we’re still several orders of magnitude smaller than Slack… but this could be something we need to contract someone to work on in the meantime so we get it right and aren’t making things worse…

Thank you both for your replies, I really appreciate it!


Following up on the toolbar role, to clarify… are you saying the role isn’t worth it at all unless it follows this pattern as described the the W3C?

Implement focus management so the keyboard tab sequence includes one stop for the toolbar and arrow keys move focus among the controls in the toolbar.

If that’s the case then I won’t implement the role until we can get the focus and arrow key controls right.


Correct, if you use the role, you promise that you will also implement the design pattern. If you are not ready to provide the design pattern yet, don’t yet use the roller either.


Is this an appropriate place to report findings from my own accessibility audit for a hosted discourse instance, or should I start a new thread?


the third-party accessibility report and subsequent work I mentioned earlier aren’t being tracked publicly.

Any chance this decision could be revisited? Would be helpful to have some transparency around this that I could share with my clients.


Hey Aaron,

To ensure things aren’t lost, I’d recommend a new #ux topic (tagged #accessibility) for each finding in your own audit. If your findings are closely related it may make sense to use the same topic for each. Essentially we want things grouped into small chunks that can be tracked independently and marked “done” without needing to worry that we missed 1 item from a list of 53 in the OP.


OK, will do.
Posted the first one here: A11y: WAVE issues from homepage though seems like I don’t have permission to tag yet.


To elaborate a bit on this:

Using the role without implementing the pattern would be a bit like styling something to look like a button, then making it only respond if someone hovers over it and scrolls their mouse wheel. If I tab to or otherwise focus a toolbar, and it exposes all of its button separately or doesn’t respond to arrows, then it feels like that odd mouse wheel button might. You’d have to think before each and every interaction, and it claiming to behave in ways it doesn’.

Hope that clarifies things a bit. Knowing that something is a toolbar is only valuable if it behaves like a toolbar. Otherwise it’s distracting.


Aww, disappointing. Came here to ask what the status was on all these updates that seemed like they were in-flight when I posted this. I haven’t launched our community yet, but the old existing PHP forum is about to die so it’s now or never. Figured there’d have been some amazing changes by now.

But I couldn’t figure out how to reach my site’s admin area. I can certainly hit /admin, but the link to the site is still not accessible via keyboard in any way I found. That makes it a bit challenging when asking screen reader users to help me moderate.

Then I tried typing this reply 5 minutes ago, but somehow I clicked either an Edit or Quote button. It dumped me into what appeared to be an editable version of a previous message I sent. I tried hitting enter on a link labeled Cancel, but that didn’t work. Neither did reloading the page. Ultimately I sent the reply, then found and interacted with an inaccessible modal like the one I reported here initially to discard the message.

Has anything changed in this regard, or is there a public roadmap yet? As a screen reader user who has to interact with Discourse communities whether he wants to or not, I can make it work for me, but I don’t feel super comfortable asking a community of blind folks to use this–or, at least, asking them to build a community they’d enjoy on Discourse.



Unfortunately, that popped up a modal asking what you wanted to do with your draft (discard/save/cancel), and it seems modal focus capture is broken…


Discourse works for me but I’d definitely like to see some accessibility improvements. Its been a while since I used the admin UI or administrated a Discourse forum, but I’d expect a lot of progress to be made in 3 months.
I understand that ARIA can be challenging, but that in no way means that progress can’t be made. @nolan I’ve suffered that same problem before – it took me a while to figure out why the edit box hadn’t vanished when I clicked ‘Cancel’. I’d really love to use Discourse as a forum for my own community sometime in the future, but I may need to reconsider that if accessibility improvements aren’t made. And I’d hate to go back to PHP.
You guys practically have someone offering to help you with accessibility. Sorry if I sound impatient – I know this is tough and is hard for you guys. But both @nolan and myself are definitely willing to help, at any rate. I’d be happy to set up a Discourse test instance.