Template talk:Screen reader-only

Template:Screen reader-only is permanently protected from editing as it is a heavily used or highly visible template. Substantial changes should first be proposed and discussed here on this page. If the proposal is uncontroversial or has been discussed and is supported by consensus, editors may use {{edit template-protected}} to notify an administrator or template editor to make the requested edit. Usually, any contributor may edit the template's documentation to add usage notes or categories. Any contributor may edit the template's sandbox. This template does not have a testcases subpage. You can create the testcases subpage here.

Some questions for the page watchers (maybe just Rexx). :^)

1. Why does this template blend a couple different ways of disappearing text? We've got both the 'negative large text indent' method and the 'clip' method sitting embedded in here (see WebAIM). It's not obvious to me that both are necessary. Caniuse indicates that how we are using clip here is supported by all desktop browsers and the majority of the interesting mobile browsers definitively (with some 'unknown's). (That said, clip is deprecated, though we can't use its replacement due to TemplateStyles non-support.) Accordingly, is there a reason that it does not use Cloud4's implementation directly?
2. Is there attachment to the current name? Sronly is not very friendly. I had in mind Template:Accessible hidden, but expanding it out to Template:Screen reader-only or some such was also reasonable for me.
3. Out of curiosity, were you aware we have a class for this in Common.css? It's .visualhide. I'm trying to get rid of it and made Template:Accessible hidden briefly for that reason, but clearly not needed. :^)

--Izno (talk) 16:50, 2 December 2020 (UTC)[reply]

@Izno: bleh; you had to wait this long to ask? Anyway, I've searched now and found the original discussion.

1. On 7 April in Wikipedia talk:Manual of Style/Accessibility/Archive 15 #Discussion, Peter Southwood asked me "Is there no way to provide an invisible caption, like the alt text for an image?" I replied, referring to https://cloudfour.com/thinks/see-no-evil-hidden-content-and-accessibility/#showing-additional-content-for-screen-readers – adding that it was "complex and requires a certain degree of browser compliance. Effectively it places the text inside a 1px square and tells the browser not to display any content inside and outside of it. A screen reader ignores those display directives and will still read the text as normal. I experimented and concluded that we don't support clip-path, so I actually did implement Cloud4's code (almost) directly. If you check the history of Template:Sronly/styles.css, you'll see that the "large negative text-indent" was added some two months later, and not by me. I don't consider it adds anything, other than confusing the browser about where the leftmost piece of text is.
2. No attachment, other than a feeling that it's simple to use. Of course, it could be moved to Template:Screen reader-only or whatever, leaving the redirect for me to use, if you think that would satisfy the need of our OCD editors to have everything "just so".
3. If I was aware of .visualhide, then I've forgotten about it. I'm 68 years old and my memory gets worse every passing day, so I have to rely on youngsters to spot these things for me. Nevertheless, if I were aware of it, I wouldn't have used it for two reasons: (1) the code there allows the 1 pixel square to display a dot, and if you move it well offscreen to the left, you'll sometimes end up with a horizontal scroll bar – maybe not on a Wikipedia page, but I've had that happen to me on clients' websites, so I dislike the "large negative text-indent" hack through force of habit; (2) If I'm using a template, I almost always prefer to apply styles at the TemplateStyles level, even if they duplicate classes in Common.css, because they are then insulated from changes in Common.css and can be fine-tuned for the particular application. You also don't have to go searching for where the class is defined (if it's defined at all).

I don't know how helpful all that is, but perhaps others will be able to shed more light. --RexxS (talk) 18:41, 2 December 2020 (UTC)[reply]

1. Yes, that was the implementing discussion (it was only 6 months ago! Maybbeeeee longer for someone who was made a victim of irrational sick people ;). The only reason I thought to ask was because I hadn't reviewed the implementation then (personally quite unhappy for its use in the general case but I CBA to fight it now that I see it is something of a web standard :^), and I just-now have the tools to nix the class in Common.css, which I'm on the prowl to do. I'll remove the not-helpful addition especially given there was no rationale provided in the edit summary, and external experts have clearly indicated it is unnecessary when employing this hidey hidey method.
2. Okay, I'll move the pages then. I'll have to see if the styles page is called directly anywhere. Doubtful, but there it is.
3. Oh, no worries. I wasn't aware of it either when I implemented exactly visualhide in a module rewrite of a template elsewhere! That said, that solution has been implemented in Template:Convert and friends for ever, so I assume it is not a particularly bad implementation on Wikipedia as I haven't noticed any scrollbars for that content (at least).

--Izno (talk) 20:34, 2 December 2020 (UTC)[reply]

On point 1 in Rexxs's reply: This is interesting. It's a variant of something I did in HTML 3 and 4 back in the 1990s for providing page-top options for text-only browsers like Lynx, while hiding them from graphical browsers: use tiny images that blend into the background and which use alt text. On point 3, I agree that using elements outside the viewpoint is a bad idea, as it does tend to generate scrollbars and cause other problems. It's much better to keep stuff within the graphical viewpoint but visually suppressed.  — SMcCandlish ☏ ¢ 😼  03:45, 15 December 2020 (UTC)[reply]

@RexxS: Can this template technically also be used for things other than text, like an entire table? If that's possible, is it also possible to make a template that tells screen readers to exclude content? For example, if a table tailor-made to be used by screen readers is placed in a {{sronly}} template above a table made for people who do not use a screen reader, could the latter be ignored by screen readers if it was in a {{srexclude}} template or something? I'm just wondering as this might be helpful as a compromise in situations where rowspan is perhaps helpful to those who do not use screen readers, but is obviously a detriment to those who do. Other style considerations/consensus would apply regardless of whether a screen reader table and a non-screen reader table are both present; this is not about avoiding that, but for a typical discography table, for example, which uses rowspan heavily in multiple columns, do you think it might be helpful if there was a version made specifically for screen readers above the standard table? Like is it possible to use {{sronly}} for things more complicated than text alone? Heartfox (talk) 06:04, 10 December 2020 (UTC)[reply]

@Heartfox: The template can be used with any content that can be properly placed inside a template, I think. It simply tells the browser to display it content in a 1px by 1px window (and then clips display even of that pixel). Using wiki-markup like tables can be problematical, because of the pipe character, so that we're better off putting an html table inside {{sronly}}. The template wraps its content inside a <span>...</span>, so any wiki-text that generates a new paragraph (blank lines, for example) will close that span, and it's necessary to keep line feeds to a minimum. The MediaWiki software will eventually produce a new paragraph when a table is present and so the browser will see the following text in a new paragraph.

For example:

{{sronly |1=
<table class="wikitable">
<caption>Example</caption>
<tr>
<th>One</th>
<th>Two</th>
</tr><tr>
<td>three</td>
<td>four</td>
</tr></table>Note here [[#next section|Skip the second table]]

gives:

which is not rendered by the browser, but is there in the html, so a screen reader can read it as normal.

Hiding text from a screen-reader is a different question altogether, and I don't know of a way of doing that within the MediaWikia software. Of course, you could work around it by having the first table inside {{sronly}} and immediately after the end of the table have a note saying something like "The table above is optimised for screen readers and only visible to them. It is duplicated below in non-optimised form. Skip the second table. The link in the note would be to an anchor inserted just after the second table. There may be other solutions or work-arounds. --RexxS (talk) 14:28, 10 December 2020 (UTC)[reply]

I would generally advise strongly against any approach of duplicating tables for any reason, for all the reasons we don't duplicate content in specific articles normally. --Izno (talk) 16:30, 10 December 2020 (UTC)[reply]

I agree with Izno above "against any approach of duplicating tables for any reason". However, I did also come here wondering whether this template or a split-off were capable of doing a "nosr" version, that is: "everyone but screen readers". A bit like how there is <noscript> to provide alternative content. One potential use of this is in the case of {{abbr}}. I'm informed that many screen-reader users do not get the title= content that provides the expansion of the abbreviation (either because their SR software cannot handle it, or because it's an optional feature they have not turned on and maybe do not even know about). We could use sronly to present an alternative, in <span> form, that gave this content as actual text (e.g.: "UN [abbrev. for 'United Nations']", and then use a "nosr" feature to suppress the original <abbr> code and its mouse-over tooltip stuff, so no screen-reader users get the content twice.  — SMcCandlish ☏ ¢ 😼  03:38, 15 December 2020 (UTC)[reply]

Moved to Wikipedia talk:TemplateStyles § HTML 5 compliance issues relating to TemplateStyles

 – I'm not seeing anything in this template causing this, so it seems to be a general TS issue.  — SMcCandlish ☏ ¢ 😼  04:12, 15 December 2020 (UTC)

W3C's validator is throwing errors when I test a page that uses this template [1]:

Error: Element style not allowed as child of element p in this context. (Suppressing further errors from this subtree.)

From line 72, column 133; to line 72, column 187

...est</span><style data-mw-deduplicate="TemplateStyles:r993651011">.mw-pa...

Contexts in which element style may be used:
     Where metadata content is expected.
     In a noscript element that is a child of a head element.
Content model for element p:

     Phrasing content.

And:

Error: A link element must not appear as a descendant of a body element unless the link element has an itemprop attribute or has a rel attribute whose value contains dns-prefetch, modulepreload, pingback, preconnect, prefetch, preload, prerender, or stylesheet.

From line 81, column 209; to line 81, column 291

.../a></span><link rel="mw-deduplicated-inline-style" href="mw-data:TemplateStyles:r993651011"/><span...

The second would seem fixable by giving it an itemprop value, or adding a value to rel, if that wouldn't break anything. Dunno about the first. And maybe these are both just general issues with templates that use TemplateStyles.
 — SMcCandlish ☏ ¢ 😼  04:07, 15 December 2020 (UTC)[reply]

Since TemplateStyles uses a <style>...</style> to define its classes, every use of any template that makes use of TemplateStyles will include a style tag at the place in the body of the page where the template is used. If you want text to comply with the specification that only allows style tags inside head elements, you will have to forbid the use of TemplateStyles completely. Good luck with that. --RexxS (talk) 16:41, 15 December 2020 (UTC)[reply]

This edit request has been answered. Set the |answered= parameter to no to reactivate your request.

Could not find the Phabricator task, but clip-path property can now be saved in TemplateStyles, see Шаблон:ЗКА:Быстрые/styles.css page in Russian Wikipedia for a quick example. Template:Screen reader-only/styles.css can be updated to reflect that. stjn 10:29, 30 April 2023 (UTC)[reply]

Done. Thanks for the notification. —TheDJ (talk • contribs) 13:30, 2 May 2023 (UTC)[reply]

[[Visible{{sronly|spoken}}]] causes:

[[Visiblespoken]]

[[Visible{{sronly|spoken}}After]] causes:

[[VisiblespokenAfter]]

[[<abbr title="hover text">Visible{{sronly|spoken}}</abbr>]] causes:

[[Visiblespoken]]

And placing [[link|<abbr title="hover text">Visible</abbr>{{sronly|spoken}}]] at the very top of a page will sometimes result in the spoken text being printed inline.

I noticed these when trying to use this to improve accessibility on template:tooltip, Rjjiii (talk) 18:08, 11 July 2023 (UTC)[reply]

Correct, you cannot do this. Text in links only support very limited html markup and hiding text with template styles (as sronly uses) are not part of that permitted markup. See phab:T200704. Sometimes the effects of these missing style definitions are not as obvious, as later uses in the page of tooltip (outside of links) manage to include a new proper copy of the styles, when get used. —TheDJ (talk • contribs) 10:02, 12 July 2023 (UTC)[reply]

I'm not sure what you are attempting to do exactly, but in general, I'd say that you should use aria-label and similar aria attributes to provide screen reader specific content, instead of using offscreen text. But picking the right strategy very much depends on what you are tying to do. —TheDJ (talk • contribs) 10:08, 12 July 2023 (UTC)[reply]

Also it should be noted that you should NEVER use {{sronly}} or {{tooltip}} as part of a 'simple' link. Any of these formatting templates can only ever be used when specifying the DISPLAY part of a link. There is no page named Visible{{sronly|spoken}}After, so it cannot be a link (the behaviour of this syntax is undefined in the wikitext grammar). Only [[PageLink|Visible{{sronly|spoken}}After]] can possibly ever be valid. And whenever that link has to be passed to a template, you will loose the styling. —TheDJ (talk • contribs) 11:16, 12 July 2023 (UTC)[reply]

Thanks, I'll try to make that clear in the documentation, also. I saw previous discussions where sronly was planned as a way to make tooltips accessible, but aria is probably a better solution. Rjjiii (talk) 19:30, 12 July 2023 (UTC)[reply]

@TheDJ: Also I made a demo of the other error that I saw. The "Spoken" text in the link will be displayed or not depending on where the link is placed on the page. Rjjiii (talk) 19:42, 12 July 2023 (UTC)[reply]

@TheDJ: Here is another example of the issue, this time not cause by being inside a link: https://en.wikipedia.org/w/index.php?title=User:Rjjiii/sandbox10&oldid=1189647875 The text like "Prostaglandin D2 receptor" is wrapped in {{sronly}}, but shows as normal. Template styles seem ignored.

But if I use it one time outside of the navbox, then it works as intended in every other usage: https://en.wikipedia.org/w/index.php?title=User:Rjjiii/sandbox10&oldid=1189648096

I wonder if inline styles could prevent this? It seems like there are several edge cases that block template styles, Rjjⁱⁱⁱ (talk) 04:15, 13 December 2023 (UTC)[reply]

Hi. Is it possible to add a third parameter to the template for text to be read only when a screen reader is not used? InfiniteNexus (talk) 04:04, 23 October 2023 (UTC)[reply]

InfiniteNexus, what is the use case for that? What content would an editor need to hide? Rjjⁱⁱⁱ (talk) 04:41, 23 October 2023 (UTC)[reply]

For exmaple, if there is text that a screen reader may not be able to pronounce correctly, such as M3GAN or covfefe, we would do {{screen reader-only|Megan|M3GAN}}. InfiniteNexus (talk) 04:51, 23 October 2023 (UTC)[reply]

What would you replace "covfefe" with? It doesn't make sense to people reading it with their eyes, either. If something's nonsensical it is just nonsensical. I think a screen reader would be apt to do as good a job at working out some kind of possibible pronunciation like /kawv-fee-fee/ as a sighted user trying to parse it. "Covfefe" doesn't appear to be a good candidate for use of this template. In the M3GAN case, I would think screen readers go with "em-three-gan" or spell it out completely as "em-three-jee-ay-en", either of which gets the stylization idea across, so again what's the use-case for this template and it having an additional parameter? The article's lead reading M3GAN (pronounced "Megan") ... doesn't appear to be broken for anyone.  — SMcCandlish ☏ ¢ 😼  05:00, 23 October 2023 (UTC)[reply]

Oh, I can see how that could make sense, but I believe you're overthinking this, InfiniteNexus. I agree with SMcCandlish; the default "em three gan" is fine. The general advice for supporting screen readers is to write clear content with simple syntax. That allows the browser and screen reader to do the heavy lifting. This page is a solid introduction: https://www.w3.org/WAI/tips/writing/ Rjjⁱⁱⁱ (talk) 05:14, 23 October 2023 (UTC)[reply]

Maybe this isn't applicable for the lead, but do you both genuinely think it is a good idea for a screen reader to say "em-three-gan" and however it thinks "covfefe" is pronounced every time the term appears in the article and on other pages? In most cases, the fact that a word is "stylized" is unimportant to the rest of the sentence. Obviously, we would use editorial judgment and avoid using the template in cases like The "3" in M3GAN refers to the fact that the robot is the third-generation model. (made-up example). InfiniteNexus (talk) 05:52, 23 October 2023 (UTC)[reply]

Yes.[2] Rjjⁱⁱⁱ (talk) 06:19, 23 October 2023 (UTC)[reply]

Yes. The reader has already been told that the title renders as "em-three-gan" and that people pronounce it the same as the name "Megan", so there is no confusion potential. This might be some kind of problem with a tremendously-long acronym that is read out letter-by-letter ("ACPDOWOISLSIEIFIWM" or something), but the solution to such a weird case would be to replace it with "the company" (or whatever), and that would be advisable anyway, since sighted readers would not need to see that jumble over and over again. In the "covfefe" case, I can't see what the alternative is; it has to be pronounced some way for the sight-impaired user, so it might as well be consistently what the screen reader decided is the best pronunciation to use, just as when I read the article on it I hear in my mind /kawv-fee-fee/ every time I see that string. It's not like we would want to force screen readers to use multiple different pronunciations of this "word". Actually, I can see a use for this template, once, at the covfefe article, and that is to present it spelled out: {{Screen reader-only|spelled c-o-v-f-e-f-e}}. Which makes me think of another use for it in a different article where a terminological difference is being drawn between jargon terms sett and set, which I now realize will probably be pronounced identically by screen readers. But none of this calls for a new parameter. Maybe there is some kind of use for the proposed parameter, but these examples aren't it. A danger with such a parameter is that editors are apt to think it needs to be filled in, and would put unwise things in it on a regular basis.  — SMcCandlish ☏ ¢ 😼  07:01, 23 October 2023 (UTC)[reply]

The "official" pronunciation of "covfefe", according to the man who insists it was not a typo, is "koh-feh-fee". Yet I just ran it through multiple screen readers, and one said "koh-fee-fee", another said "koh-fef", another said "koh-feh-feh", and another said "koh-feh-fee". InfiniteNexus (talk) 16:41, 23 October 2023 (UTC)[reply]

Given that it's nonsense to begin with, I don't think we need to care what the "official" pronunciation of it is, other than to take note of that somewhere in the article, once. There's no practical reason to jump through a bunch of coding hoops (and editorial template-usage hoops) to force screen readers to render it that way at every occurrence. We have more important things to do with our limited volunteer time. We already have, a zillion times more commonly, various personal and geographical and trademark names, of real entities not made-up nonce words, that screen readers do not handle exactly matching the "official" pronunciation, or even consistently between screen readers, and this has not made the sky fall down. If we were going to address that issue, it would be on the basis of actual proper-name handling, not nonce words, but there has been no hue and cry to do that. And adding a parameter to this template doesn't seem to relate to solving that anyway. So these are probably separate discussions.  — SMcCandlish ☏ ¢ 😼  23:18, 23 October 2023 (UTC)[reply]

Agreed, this doesn't matter. Screenreaders are not intended for accurate pronunciations. The solution for this specific case, is to simply add the pronunciation with the {{audio}} —TheDJ (talk • contribs) 08:57, 24 October 2023 (UTC)[reply]

This template will occasionally fail to hide the text. It's not just within links, but I'm not sure what all scenarios cause it. It looks like in some situations the template styles are never given to the browser. I put the CSS inline in the sandbox, and the issues seem to go away.

• Using proper templatestyles with errors: [3]
• Using inline styles with no errors: [4]

This packs the presentation into the content though, Rjjⁱⁱⁱ (talk) 23:08, 26 December 2023 (UTC)[reply]

I think MOS:HIDDEN should apply to this template and contents using the template, not limited to just <!-- hidden text -->. Should it? After all, the template visibly hides the content just for screen readers to read it aloud. I thought about mentioning MOS:HIDDEN in the doc subpage, but I'm raising the matter here instead. George Ho (talk) 22:32, 5 September 2024 (UTC)[reply]

Hidden text is for the benefit of editors. This template is for text that benefits those using screen readers. Thus the guidance on hidden text wasn't written with the purpose for this template in mind, and is not applicable. isaacl (talk) 23:56, 5 September 2024 (UTC)[reply]

Yeah, this template is meant for something other than hidden comments. For example, it can be used to add a caption to a data table that would otherwise appear redundant: Wikipedia talk:Manual of Style/Accessibility/Archive 16#Making redundant table captions screen-reader-only Rjjⁱⁱⁱ (talk) 01:38, 6 September 2024 (UTC)[reply]

I use MS Edge on Windows 11 and this template does not work there. In the documented example, it reads "First part" and skips straight to "Third part". Thanks! —CX Zoom[he/him] ^{(let's talk • {C•X})} 08:40, 25 June 2025 (UTC)[reply]

That's the way it's supposed to work. As the documentations says, This template generates invisible text …, and Second part only for a screen reader. -- Michael Bednarek (talk) 15:02, 25 June 2025 (UTC)[reply]

I tried to mean that the "Read aloud" feature on Edge reads "First part" and skips straight to "Third part". —CX Zoom[he/him] ^{(let's talk • {C•X})} 15:42, 25 June 2025 (UTC)[reply]

I suspect MS Edge's "Read aloud" is not a proper screen reader. Does it read out alt text of images? -- Michael Bednarek (talk) 15:53, 25 June 2025 (UTC)[reply]

Looks like it doesn't. —CX Zoom[he/him] ^{(let's talk • {C•X})} 18:49, 25 June 2025 (UTC)[reply]

Is there any particular reason why this template uses its current (quite complex) CSS instead of just 2 properties - position:absolute; and left: (or right:)? Sapphaline (talk) 09:54, 27 August 2025 (UTC)[reply]

I assume you mean something like left: -9999px. The clip technique is better, because if you just position something offscreen, it's actually positioned there, and that might interfere with features that depend on the placement of content on the screen (for sighted users) – for example, the table of contents highlighting current section, or the links in the timestamps of discussion comments (like on this page) that draw a background behind the comment. If the screen-reader-only content contains any interactive elements (e.g. links), it can also cause the browser window to scroll towards the offscreen element (e.g. all the way to the top-left corner) when that element is focused using the keyboard. Whereas if you hide something with clip plus the other rules to make it zero-width and zero-height, it's still logically positioned in a reasonable place, it's just invisible. Matma Rex talk 15:23, 27 August 2025 (UTC)[reply]

Ok, thanks. Sapphaline (talk) 16:22, 27 August 2025 (UTC)[reply]