Screen Readers do not expose SplitText

[aardrian]

The "Screen Reader Accessibility" section on the SplitText page claims support for screen readers but misses some important caveats.

Specifically the "Built-in Aria*" section talks about using aria-label and applies it to an <h2> in the example code.

The SplitText animation demo, however, use a <div>. It seems reasonable a user would not always apply SplitText to a heading and might use code from the demo.

So here are the challenges:

• The demo uses a <div>, which in the HTML AAM maps to the generic role.
• The generic role does not allow itself to be named by the author — which means aria-label is prohibited on it.
• The demo uses headings, which allow aria-label, but without any explanation why.
• Further, aria-label may not auto-translate for users.
• The page also doesn't mention WCAG SC 2.5.3 Label in Name risks when aria-label is applied to any control (such as a button, though it does address links by duplicating text).

My suggested changes:

• Identify which HTML elements / ARIA roles support aria-label.
• Counsel against using any that don't.
• Warn of auto-translation risks.
• Warn against using on any interactive control.

I also performed screen reader testing against the linked demo:

Pairing	Works?
NVDA / Firefox	yes
JAWS / Chrome	no
Narrator / Edge	no
VO macOS / Safari	no
Orca / Firefox	no
TalkBack / Chrome	yes
TalkBack / Firefox	no
VO iPadOS / Safari	no

The YouTube video embedded on the page shows a screen reader demo, but without knowing which screen reader and browser pairing was used, I tried a few.

[aardrian]

I understand a Masto user made a video that may have coincided with an emailed bug report on 12 May 2025:
https://gsap-split-text-a11y.eu.dev.monkapps.com/SplitText_aria_VoiceOver_iOS17.6.1_Safari17.6_iPhoneProMax12.mp4

Edited to add the test page behind that video:
https://gsap-split-text-a11y.eu.dev.monkapps.com/split-text-aria-error.html

I've also made videos for the first 5 table entries above, in case those would be helpful.

[jackdoyle]

Hi @aardrian

Thanks for the detailed information. Just to be clear, you're not reporting any issues with SplitText itself - you're just asking for some minor improvements to the docs so that people understand ARIA limitations better?

[aardrian]

This issue is not reporting bugs with SplitText. Those may be separate issues (because there are some). I filed this first because it seemed like the easiest thing for the team to address immediately.

And to be clear — these are not ARIA limitations. This issue reflects the documentation's need to better convey how to use ARIA correctly, per spec.