lib components / Text

Screen Reader Only (SrOnly)

Wrap this invisible component around text that needs to be hidden visually, but kept available to assistive technologies, such as screen readers.

Examples Properties Guidelines

import { SrOnly } from "@siteimprove/fancylib";

#Examples

We sometimes leave out text in our UI, because it creates visual clutter and its message is communicated through context. That explains why some of our table column headers are empty. Despite the empty headers, the content and purpose of the columns remains clear to sighted uses.

This is not the case for non-sighted users and that’s where the SrOnly component comes in. This component enables us to hide text, but keep it available to assistive technologies, such as screen readers. So, empty table column headers actually do have labels, they’re just hidden from view.

#Default

The example below may seem empty. However, the Code section shows that it actually contains an SrOnly component wrapped around a sentence. If you toggle on the HTML output, you'll see that this component outputs a div.

CodeHTML output

<SrOnly>This text is invisible, but available to assistive technologies.</SrOnly>

#Status

When the status of an element in the UI changes, this is sometimes only communicated visually. The status property enables us to keep assistive technology users informed of such changes. When set to true, role=“status” and aria-atomic=“true” are added to the div that the SrOnly component outputs. As a result, whenever the content of that div changes, its new content is announced to assistive technologies, such as a screen reader.

This doesn't work:

isLoading && <SrOnly status>Loading</SrOnly>

For the status property to work, the SrOnly div must be present in the DOM before its content changes. This means the condition that triggers the content change, must be placed inside the SrOnly component. You can see an example of this below.

CodeHTML output

<SrOnly status>{isLoading && "Loading"}</SrOnly>

#Focus

This component can also be used to assist sighted users who navigate using the keyboard. SrOnly components are visible when given focus. This functionality can be useful, for instance, to create links that make it possible to skip content so that it is not captured by assistive technology devices, such as screen readers.

CodeHTML output

<SrOnly>
	<Link href="#properties">Skip to properties section</Link>
</SrOnly>

#Properties

CodePropsHTML output

Property	Description	Defined	Value
childrenOptional	`element`Content of the element	YesNo
statusOptional	`boolean`Notifies assistive technologies of changes to the content. WARNING: SrOnly component must be present before content change for this to work.	YesNo	truefalse
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo
isInlineOptional	`boolean`Will replace the SrOnly div with a span	YesNo	truefalse
idOptional	`string`Optional ID	YesNo
aria-hiddenOptional	`boolean`Indicates whether the element is exposed to an accessibility API.	YesNo	truefalse

#Guidelines

#Best practices

Use when important information is only communicated visually.
Use to hide text visually, but keep it available to assistive technologies, such as screen readers.
Use the status property to announce changes in the UI to assistive technologies.

#Do not use when

Semantic HTML can be used to communicate the same information to assistive technology users.
The wrapped content is interactive. Interactive content should always be visible.

#Accessibility

Preferably, all content should be the same for all users, regardless of their use of assistive technology. Use this component sparingly and only when semantic HTML or an aria-label don't suffice. Consider consulting an accessibility specialist before using it.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

The purpose of any information you include should be to help blind and low vision users successfully navigate the platform.
Don’t repeat textual information that is already present in the UI.
Make sure all information is useful and relevant to the task at hand. Don’t overcompensate out of fear or uncertainty.
Go for clarity over brevity. Don’t skip words, and spell out any abbreviations in full (except for more common ones like SEO).
Be aware of words that are spelled the same but are pronounced differently (like “read” present and “read” past) — make sure the meaning is clear from the context
It might sound obvious now, but remember not to rely on visual cues in your explanations. For example, don’t say “Click the pen icon in the right-hand column”.
Don’t use all caps for emphasis — this may be announced by the screenreader as an acronym.
Formatting (such as bold text, italics, etc.) is redundant — most screenreaders will ignore it.