Discourse with a screen reader

Sure, we appreciate the offer! If you see any easy changes, can you provide specifics? Many of the accessibility changes we are working on require restructuring the application, but we’re always game for any low hanging fruit.


A list, in no particular order with the exception of the first item:

  1. You have modals that don’t grab focus, which was what made me write this post in the first place. Anyone coming to this thread to give screen reader usage feedback is going to hit one of these, meaning that basic/intermediate screen reader users are filtered out. I haven’t hit this on my forum, thankfully, just here. Hopefully there’s some way I can turn these off, or at least, turn off whatever conditions would cause one to appear. The only way to interact with these is to wonder why none of your keyboard commands aren’t working, and to know enough about how web apps work to think of hunting for a modal. Then, once you’ve found it, you have to interact with it and navigate focus to the correct control. And even then it isn’t always reliable, as exhibited by my struggles replying to this topic.
  2. When I click a topic, keyboard focus doesn’t move automatically to the newest post. I’m not sure what’s supposed to happen here, so maybe there’s a different link I need to accomplish this? As such, keeping up with new posts is hard, and something I still have to do manually.
  3. There is no apparent way to reach my site administration area via the keyboard. I had to guess that /admin might work as a URL, and fortunately it did.
  4. ARIA landmarks in the forum posts would be useful. Essentially, make each post something like an <article/>, with <heading/> for the top controls and <footer/> for the bottom. This enables faster navigation by landmark, since there aren’t currently useful ways to move between posts quickly. I can sort of do that now via NVDA, but doing so drops me on the including the Like and other buttons. If the actual landmark elements won’t work, a role= attribute will.
  5. If I click the Topic actions button, there is no way to close the menu that appears via the keyboard.
  6. Your list widgets are kind of an accessibility disaster. I just tried moving a post with NVDA. Here’s how I did it:
  7. Clicked the Edit title/category button. I don’t remember exactly what this was called since, again, I can’t collapse the screen to get the button back.
  8. Found the category combo box.
  9. Activated it with space.
  10. Used NVDA object navigation to zoom into the selected combo box item, which was not at all intuitive.
  11. In that item, there is a list. I interact with it.
  12. In that list there is a search field, and another list. I interact with that other list.
  13. I then move through what appear to be a bunch of category descriptions, again with NVDA object navigation, until I find the one I want. I route the mouse to that.
  14. I click the mouse with NVDA.
  15. I suspect there’s another step where I have to find and click an unlabeled Save button, but I’m not sure and certainly won’t remember this the next time I have to do it. :frowning:
    As you might imagine, this is not intuitive, and something I only discovered because a) I’m probably an intermediate NVDA user b) I do web development among other things and c) I’ve kind of learned the ways in which Discourse does things.
  16. There are various unlabeled graphics which don’t identify as buttons, but which appear to do things. I think the Save buttons in the admin screens are an example. I’m sort of hesitant to randomly click unlabeled buttons on a live site relied on by users. That kind of thing is likely to bite me in a painful place someday. :slight_smile:

I’ll give things about a month, then I’ll slap PHPBB or something more accessible on a server and we’ll just go with that. Sorry, I’ve got a lot of folks not even giving the community a shot because of these issues, and given that the broken modal was quite literally the first speedbump I hit, I’m probably going to have to do what we as blind folks do far too often and pick the technically inferior but more accessible option. :frowning: Not trying to be grumpy, I just wish my choices for community weren’t a bunch of accessible options with smaller communities and less development, a great option with major accessibility issues, and mailing lists.

BTW, I’m a senior developer available for hire if you need help. To be frank, Discourse is eating enough of the internet that a bunch of us with disabilities have to grudgingly deal with accessibility issues like these when our well-meaning able-bodied colleagues set up a Discourse for their projects. And I get why they do, because I’d very much like to use it for our community, and you’ve created a product that is amazingly easy to administer. But if you don’t have an accessibility lead fixing current brokenness and ensuring that all new features are usable by people with disabilities, then let’s talk please, because you desperately need one. :slight_smile: The only reason I tried Discourse here is because I came away from this thread thinking that major accessibility changes were imminent. But in general, I actively discourage Discourse use whenever I have a say in it because of how hard it is to use with a screen reader, and because I don’t want to create another internet community where we as blind people can’t participate equally because of access issues. I’d love to change that, and to be a part of making that change happen. But if not me, then please bring someone on, because many of these issues have been around for years and haven’t changed to any significant degree.



Wow! Thank you for the detailed and thorough feedback!

I’m sorry, I don’t understand. I’m not aware of any modals that appear on visiting a topic? Are you referring to the editor / composer that one uses to write replies to topics, which I am typing in right now? Are you referring to the editor that appears after you press a reply button anywhere in the topic?

Since this is the first and most urgent issue, I’d like to understand it. Let’s maybe go step by step and start with the most important issue, since we’ve had blind users before and have acted on their feedback in the past – for example here:

and here

Perhaps we regressed recently? I want to understand what this “modal” is you are referring to.

(Also, did you try pressing ? to get the list of keyboard shortcuts? One thing I just noticed when investigating “how to get to admin area via keyboard” is that pressing = will get you to the hamburger menu but nothing in it is selected cc @sam – we should definitely fix that one.)


Hello, @ndarilek here. :slight_smile: Looks like I have another account here, didn’t realize I have two now. Maybe that’s why my email address didn’t work when I tried signing up in February. Here’s a quote from the first post about the modal I hit on signup. Note that there are a few issues listed in that post, some of which are likely duplicates of the ones I listed here. I think that part of my frustration is raising these again and again, and not knowing where to go to ensure that a) they’re rceived and b) that you’ve got the information you need. These modals in particular are hugely problematic because a) they’re hard to find for screen reader users and b) they block all input from reaching the page, so all of a sudden Discourse refuses to do anything when links/buttons are clicked. Anyhow, the quote–not sure of the quoting syntax:

• 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:

Thanks, hope that helps.


OK, definitely hearing you, I’m still trying to figure out what this means:

Are you referring to the editor, the overlay pane that is used for editing in Discourse? I assume you must be? This is indeed not a modal, it is an overlay pane that stays with you, docked to the bottom of the browser, and “rides along” as you navigate through the Discourse site. You can collapse the editor to a single small summary line, or even expand the editor to fullscreen as desired, all the while you can keep reading topics in Discourse – even navigate to completely different topics – while you are composing your reply. This fits the theme of “encourage as much reading as possible” in Discourse, in that you can continue to read and navigate the site, your reading experience is not interrupted by the editor, as it is an overlay pane, docked to the bottom of the browser window.

The editor has two primary action buttons at the bottom left:

  • Reply – this closes the editor overlay pane and submits your reply to the topic (or to a different topic, if you have navigated away from the original topic)
  • Cancel – this closes the editor overlay pane and either saves the in-progress reply as a draft, or discards the draft

The editor also has a few other functional areas:

  • A “grab bar” along the top edge of the editor so you can control the overlay pane height, and adjust it up or down
  • An “editor type” button at the top left which lets you switch from a reply, to a personal message, to a new topic that references the original post
  • A “expand to fullscreen” glyph button at upper right
  • A “collapse” glyph button at upper right
  • A “hide preview” glyph button at bottom right. Pressing this button twice will show the preview again.

The editor should definitely grab focus when you press the reply button, e.g. “I am initiating a reply to this post.” It does in my testing, on both desktop, laptop, tablet, and phone. It switches to keyboard input and grabs focus when you press the reply button on the topic, or the reply button on any individual post.

Sorry if it takes a while to get to this work, we want to do it, it’s just that we have an overwhelming amount of work and a limited number of engineering hours, plus there’s an ongoing global pandemic that has had deleterious effects on many of us, and a number of the team have contracted COVID. I apologize; the best I can say is to pick out the most important issues and we’ll do the best we can to work on them first.

(Re-reading this, are you instead referring to the account signup process? It is possible we regressed there on accessibility as we did enhance the signup dialog in the 2.7 release?)


Aha! Finally something I can actually understand and repro. @sam I see what’s going on here… go into editor, type a bit of text in the editor so it wants to save a draft… press tab twice to be on the cancel button, then press enter. This dialog should now have focus, but does not – when I press tab I am on some other element. We should fix this and backport.


So my thoughts on this.

I’m on he fence really. I’m on Linux using Orca (which is the built in screenreadr) and it is seriously lacking, at least on my machine, for table navigation.

My main issues are two fold

First off. I don’t know where I am in a thread since there’s no easy way to keep track of individual posts. I can’t jump directly to the nexxt post in a thread, instead I need to scroll past all the add reply/bookmark/share a link/etc things to get to a new post

The layout is, for me at least, a mess of buttons and links everywhere. If things had headings, such as okay, heading 1 for the top bar, heading 2 for the first post in a topic, and heading 3 for each successive post I could live with that since it’d allow a screenreader user to quickly jump from one post to another without being caughtg up in all the clutter such as sharing links, liking posts and bookmarking.

Before I get told oh, do this, this, this, this and this settings wise. No. I shouldn’t have to go tweak a bunch of settings to make Discourse useable on my system.

What Discourse has done is great, really, on paper.

But why must I wade through a billion buttons just to get to a topic, or a thousand links? Okay. I’m exagerrating a bit, but hear me out.

This may be an opinion thing. but. I am used to things like pHP based forums that have headings for most things. So I’ll ask and would like to know if the lack of headings is a design choice or something that can be worked on to improve accessibility?

I’d suggest testing with Windows, Mac and Linux screenreaders, the built in ones for the latter two and NVDA (which can be found at NVaccess.org and Jaws (which you can get a demo version of for evaluating Discourse with for free because the software itself is paid and as much as a Mac), as well as Microsoft’s built in Narrator for Windows.

Phone navigation? I’ll leave that one be since I don’t have a phone with me currently to test. Not all screenreaders treat tables the same way. For example, on this topic, Orca (for me) doesn’t show the thread as a table, only the one that starts with ‘new activity’ in it and it skips completely over the topic and replies. If I go by heading, after going to the very start of a topic (which is a common navigation for screenreader users) it jumps down to the list of recommended topics after the last post, which is flagged as heading level 3.


Thanks for the report again @nolan… to address the first issue first, it looks like we’re not grabbing focus on most modals… this seems like a large regression we should fix as soon as possible (this week ideally)!

Definitely understand this, and while I can say we’re working on accessibility issues… we’re not going to have our current list completed within a month.


Yeah really sorry about the giant regression @nolan on dialogs! I didn’t understand how bad that was until I looked into it. We should have held up the release for it, it’s so bad!


Thank you! I installed NVDA today and am slowly getting a feel of the issues you are experiencing.

I completely understand the desire of getting Discourse working in a reasonable way using default bindings. I also understand much better the frustration around navigation.

I can see the phpBB tricks. NVDA is extremely limited there are not a lot of shortcuts to pick from.

The heading trick is unlikely to work on Discourse cause we allow users to enter custom headers in posts. For example:

heading 2

heading 3

heading 4

There is no “next article” button, best we have is “next region”, region support is somewhat flaky compared to JAWS. We already had an article element but NVDA did not respect it.

I made this PR to at least help people be a lot less lost when navigating through a topic:

I still feel the structure is not ideal. For example, the down button, gets trapped cause of our nested double-button in our post nav.

@eviltrout is investigating the focus issues with various dialogs, we are going to have to double test with NVDA to see if our fixes take.

We have quite extensive keyboard shortcuts if you quit browse mode, but I do get the reluctance of heading down that dark corner. The trouble is that once you are in “edit” mode you have to kick out of it to actually read the content.

For example:

j → computer says “article link visited”
down → computer says “link benno”
down → computer says “march 15”
down → computer starts reading post

After my fix there will be a major improvement

Instead of saying “article link visited” the computer will start saying “post #6 region article link visited”

Improvements here are going to be gradual, but we very much appreciate all the feedback. We are learning and will do our best to make Discourse more enjoyable to the blind community.

Modals feel like a general hornets nest. If we have a modal open and for any reason you manage to navigate back to the page you can get extremely confused. I do wonder if there is someway of signalling to NVDA - Hey NVDA … all these elements … no longer exist while the modal is open. We could pull them out of the DOM while modals are open but that may end up causing even more confusion.


On Orca (Linux’s one that I use, though the controls are different, it is much the same functionality wise. I can skip to the next landmark, however that is buggy and can indeed et stuck on things. Where would I find these keyboard shortcuts given I’ve been using other forum software. I’ve not got access to a Mac, but on Linux I can leap to my next landmark on a post, for example from like button to like button on this topic for example, which goes like this:

Click topic

Go down to first post

Press M
Get to landmark, then go down
Repeat the above until you get to the end of the topic. Now, this may be browser dependent, I am not sure of that however, I haven’t tested with anything other than the default Firefox as of right now.

EDIT: Okay. This is one I jus literally ran into. I wanted to check my profile on Mozilla Firefox, however selecting the profile/notifications link at the top locked up keyboard input for me until I went to browse mode again, I’m not sure if that’s part of the dialog issues, since the page acted like I wanted to read the thread. It said expanded on the link however so I assumed it was a drop down menu I could arrow/mouse around with no luck


Your point about NVDA not respecting articles as regions is a good one. I didn’t even realize the article tag was being used until I enabled its presentation of articles yesterday, though this doesn’t seem to change the detection algorithm. I’ll file an NVDA issue about this today and see what comes of it.

Also, I get that headers can be inserted into messages. The goal of header navigation isn’t to counter that, but to help in the 99.99something percentile of cases where posts don’t contain additional headers. :slight_smile: I set up a dev environment yesterday and will investigate slapping some ARIA roles on something in .post-topic to make it easier to work with.

Modals are indeed tricky. Here is a practical guide that should help. The key takeaways are 1) use the new aria-modal attribute to indicate that the modal should show and everything else should be hidden 2) move keyboard focus to the first focusable element and 3) return focus to whichever button initiated the flow when the modal closes. Hope that helps.


Fair points, and sorry again for being grumpy. I’m context-switching daily between Discord, Element, GitHub, Gitea, and now Discourse to get things done. They all have their own respective friction points–it’s just that Discourse’s are biting me particularly hard right now because, for instance, we’ve already had an extreme problem user from the previous forum join and an advanced screen reader using co-admin spent half an hour failing to navigate the suspension duration dropdown. Thankfully I’m familiar with the dropdowns and suspended the account before he caused trouble, but we need to get to grips with this so my admin team doesn’t require so much onboarding. :slight_smile:

Glad we’re getting the modals sorted–I do very much appreciate that. I’ll spend some time today seeing if the topic display can be made any more accessible. I’d say the next big issue is the inaccessible dropdown component. In addition to not being able to suspend users, we had another member recently who couldn’t move his topic. Here is an accessible listbox example that may help. These are so pervasive that fixing them would net a whole bunch of wins.

Thanks again.


Not sure I’d create the region in addition to the article since it’s slightly more verbose.

I opened this issue making the case for NVDA tracking articles as regions for purposes of navigating to the next/previous landmark. Hopefully that will resolve the issue in the medium term.

Meanwhile, I opened this PR adding a non-visual second-level heading role on the post metadata field. With this patch applied to my test instance, h/H navigates between posts without headers. Admittedly this scheme breaks down if the post itself contains headers, but I’d argue that as screen reader users we’re used to that type of mixed content, and until NVDA considers articles as landmarks, having a quick way to skip to the next post is better than introducing filler regions.


Sam, would it be worth as an idea, putting in a non visual seperator to work around the headings in posts issue as an example, since headings can be put in posts? I was reading your post and am not sure if there’s something cross platform that can be invisible but be used to mark a boundary between posts?

Right now on Orca on Linux, I can hit 1 to go to heading 1 and the start of a thread, then use M (which is next landmark) to get from post to post. Yes it’s clunky, but is doable. I do wonder therefore if having the post # like post #1 post #2 and so on marked as landmarks instead of having a header that can also be put in posts would work on a technical and usability perspective? If the buttons below a post are landmarks, why can’t a post number be one as well? To me that’d make sense to have a post number as a landmark as well as/instead of the buttons below a post, since those buttons can be hidden away if forum admins choose (I know of one case that’s put those buttons under a more… menu)


Another apology @nolan for getting this one so wrong – clearly we aren’t testing keyboard at minimum before release and that’s a horrible baseline to miss. This is completely on us, we screwed up, and I’m frankly embarrassed how badly we did here… even the most cursory of checks would have shown us that the cancel dialog was totally broken with the keyboard, and we went ahead and had a release with that enormous bug in it. :man_facepalming:

We’re re-evaluating our process to make sure we account for

  1. keyboard should work as expected, as an absolute minimum; every feature is tested with the :computer_mouse: mouse disconnected to make sure it has proper tab order and focus

  2. core activities in Discourse should be straightforward when using NVDA

We appreciate you sticking with us on this and holding our feet to the fire. We’re rebuilding some of our process to make sure that we, at minimum always have functional and sane :keyboard: keyboard navigation. We’ll need your help to determine what makes sense as far as lowest hanging fruit on NVDA changes and optimization.


Thanks a bunch, my admin team and I appreciate it! :slight_smile:


@Nolan, so you would prefer I revert the region change and just take in the header change? Or we do both?

I am fine to try things, I did think there was some “orientation” value in having the post number announced. Otherwise it is super hard for you to tell if you are at post 100 or post 3. It has a grounding effect.

@celtichawk regarding header suppression, I think I agree with Nolan, headers are extremely rare in posts so it only should get in the way rarely.

We don’t really have a post #1 anchor to use anywhere, our only anchor is post metadata / post body and post buttons. The metdata has username / edit status / edit time, not a post number. Nolan was experimenting with anchoring the post metadata.


I just noticed how annoying it is to navigate topic lists due to lack of headers.

@nolan / @awesomerobot , should our topic titles in the topic list be an H2 or H3? Barring that we can certainly add role="heading" to topics in the topic list.

How do you navigate between topics in the topic lists today with NVDA?


I just added a region for “topic actions” eg: admin options,share,bookmark, flag,reply,tracking state.

It is a very small change, but should make it much easier to reply to topics.

I also noticed changing topic tracking state (from tracking / watching etc) is completely broken on screen readers, will discuss possible fixes with @joffreyjaffeux