# Animated headings split into single letters

Source: https://easeweb.dev/learn/split-letter-text
Topics: Page structure > Reading order matches the visual order (WCAG 1.3.2)
The fix: Either keep the words for screen readers and hide the letters: the words once as visually hidden text, the animated letters under aria-hidden="true". Or animate whole words instead of letters. On a heading, link or button, an aria-label with the words and the letters hidden also works.
Test with: screen reader
References: https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html https://www.w3.org/WAI/WCAG22/Techniques/failures/F32 https://www.w3.org/TR/wai-aria-1.2/#namefromprohibited https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden https://splitting.js.org/guide.html https://gsap.com/docs/v3/Plugins/SplitText/ https://gsap.com/resources/a11y/ https://css-irl.info/how-to-accessibly-split-text/

This is a recreated teaching example, not a finding about a named client. The code is a starting pattern: test it in your own product. No completed assistive-technology test is claimed here.

## What happens

A planning app's home page opens on a deep blue hero with one large heading: Plan your week in minutes. As the page loads, the letters rise into place one after another, a few hundredths of a second apart. To animate each letter on its own, a script splits the heading before the animation runs: every word becomes an element, and every letter inside it becomes an element of its own, with `display: inline-block` so that it can be moved and faded. Splitting.js writes this markup, and its recommended stylesheet sets `display: inline-block` on each word and letter. GSAP's SplitText makes letters inline-block in the same way.

Sighted visitors see a sentence. What the browser passes on is something else. In Chrome's accessibility tree, the heading is named "P l a n y o u r w e e k i n m i n u t e s": a space between every letter, and nothing to show where one word ends and the next begins. We checked this in Chrome's own tree, not only in a library's notes, with letters in inline-block spans, inline-block divs inside word boxes, and plain spans in a flex row: all three gave the same run of letters. A screen reader reads what the tree gives it. Depending on the screen reader and its settings, a person hears the letters one at a time, or a string of sounds the speech engine guesses at, and the headings list shows the heading as letters too.

## Why it fails

WCAG 1.3.2 asks that when the order of content affects its meaning, a correct reading sequence can be determined from the code. The letters of a word are the smallest such sequence, and here the code no longer holds the word: it holds a row of separate letters. W3C's failure F32 describes the same result reached another way, with spaces typed between the letters of a word to space them out. There, the spaces are in the text. Here, the text has none, but each letter is a box of its own, and the browser passes on each box's text apart.

Layout decides it. A letter in a plain inline span stays part of the word around it, and Chrome names a heading of inline letters "Plan your week in minutes". Once each letter is laid out as a box, with `display: inline-block`, or as the item of a flex or grid row, Chrome treats each as its own piece of text, and the space between the words is lost as well.

## Who is affected

The heading is usually the first thing on the page and the one line that says what the site is for, so it is the line a screen reader user most needs to hear as words. A split link or button has the same problem, and is worse: its name in the links list, and the name voice control users say to press it, is the row of letters.

## What automation and AI miss

To a scan, the heading is fine: it is a heading, it has text, and every letter is real text with enough contrast to measure. No axe rule looks at how a word is laid out. axe meets the letters in one case only: it won't fail the contrast of text a single character long, since it can't tell whether one character is actual text, so a letter whose contrast falls short is listed as a check it couldn't decide, not as a failure. A letter with enough contrast simply passes. An AI assistant reading the template sees `Plan your week in minutes` in the source; the split is made by a script at run time. EaseWeb's audit reads the page as rendered and reports three or more single-letter boxes in a row in a heading, link or block of text as `ew:split-letter-text`, quoting the letters as Chrome gives them. Where axe leaves letters undecided, its contrast check measures them as the word they make, from a screenshot of what is behind them.

## Before: a heading split into letter boxes

```html
<section class="hero">
  <h1 class="hero-title">
    <span class="word">
      <span class="char" style="--char-index: 0">P</span>
      <span class="char" style="--char-index: 1">l</span>
      <span class="char" style="--char-index: 2">a</span>
      <span class="char" style="--char-index: 3">n</span>
    </span>
    <span class="word">
      <span class="char" style="--char-index: 4">y</span>
      …
    </span>
    …
  </h1>
</section>
```

```css
.hero-title .word,
.hero-title .char {
  display: inline-block;
}
@media (prefers-reduced-motion: no-preference) {
  .hero-title .char {
    animation: rise 0.5s ease-out backwards;
    animation-delay: calc(var(--char-index) * 30ms);
  }
}
```

```js
Splitting({ target: '.hero-title', by: 'chars' });
```

- Each letter is an inline-block element of its own.
- So Chrome names the heading "P l a n y o u r w e e k i n m i n u t e s", with no break between the words.
- The headings list, and anything else that reads the heading's text, gets the same run of letters.

## After: words for screen readers, letters hidden

```html
<section class="hero">
  <h1 class="hero-title">
    <span class="visually-hidden">Plan your week in minutes</span>
    <span class="letters" aria-hidden="true">
      <span class="word">
        <span class="char" style="--char-index: 0">P</span>
        <span class="char" style="--char-index: 1">l</span>
        <span class="char" style="--char-index: 2">a</span>
        <span class="char" style="--char-index: 3">n</span>
      </span>
      <span class="word">
        <span class="char" style="--char-index: 4">y</span>
        …
      </span>
      …
    </span>
  </h1>
</section>
```

```css
.hero-title .word,
.hero-title .char {
  display: inline-block;
}
@media (prefers-reduced-motion: no-preference) {
  .hero-title .char {
    animation: rise 0.5s ease-out backwards;
    animation-delay: calc(var(--char-index) * 30ms);
  }
}
.visually-hidden {
  position: absolute;
  width: 1px;
  height: 1px;
  overflow: hidden;
  clip-path: inset(50%);
  white-space: nowrap;
}
```

```js
Splitting({ target: '.hero-title .letters', by: 'chars' });
```

1. Put the words in the heading once, as text that is hidden on screen but kept for screen readers. The heading is now named "Plan your week in minutes".
2. Wrap the letters in an element with `aria-hidden="true"`, and split only that element. Screen readers skip the letters, so the words are read once.

This fixes the Before and passes 1.3.2, on any element: a heading, a link, a paragraph. The animation is unchanged. The words are written twice, so keep the hidden copy and the letters built from the same string.

## After: whole words animated

```html
<section class="hero">
  <h1 class="hero-title">
    <span class="word" style="--word-index: 0">Plan</span>
    <span class="word" style="--word-index: 1">your</span>
    …
  </h1>
</section>
```

```css
.hero-title .word {
  display: inline-block;
}
@media (prefers-reduced-motion: no-preference) {
  .hero-title .word {
    animation: rise 0.5s ease-out backwards;
    animation-delay: calc(var(--word-index) * 80ms);
  }
}
```

```js
Splitting({ target: '.hero-title', by: 'words' });
```

1. Split the heading into words, not letters. Each word stays whole, and the spaces between them stay in the text, so Chrome names the heading "Plan your week in minutes".
2. Animate the words, one after another.

This fixes the Before and passes 1.3.2, with no hidden copy and no ARIA. It changes the look: the heading rises word by word instead of letter by letter.

## After: a name on the heading, letters hidden

```html
<section class="hero">
  <h1 class="hero-title" aria-label="Plan your week in minutes">
    <span class="word" aria-hidden="true">
      <span class="char" style="--char-index: 0">P</span>
      <span class="char" style="--char-index: 1">l</span>
      <span class="char" style="--char-index: 2">a</span>
      <span class="char" style="--char-index: 3">n</span>
    </span>
    <span class="word" aria-hidden="true">
      <span class="char" style="--char-index: 4">y</span>
      …
    </span>
    …
  </h1>
</section>
```

```css
.hero-title .word,
.hero-title .char {
  display: inline-block;
}
@media (prefers-reduced-motion: no-preference) {
  .hero-title .char {
    animation: rise 0.5s ease-out backwards;
    animation-delay: calc(var(--char-index) * 30ms);
  }
}
```

```js
const title = document.querySelector('.hero-title');
title.setAttribute('aria-label', title.textContent.trim());
Splitting({ target: title, by: 'chars' });
title.querySelectorAll('.word').forEach((word) => word.setAttribute('aria-hidden', 'true'));
```

1. Before splitting, give the heading an `aria-label` with its words. The heading is named "Plan your week in minutes".
2. Hide every word box with `aria-hidden="true"`, so the letters aren't read as well as the name.

This passes 1.3.2 on a heading, a link or a button, and it is what GSAP's SplitText does by default since version 3.13 (its `aria: "auto"` option). It is not enough on its own elsewhere: ARIA allows no name on a paragraph or a `div`, so the same split there leaves screen readers no text to read.

## Which option to use

All three pass on a heading. Animating whole words is the plainest: there is nothing hidden, nothing written twice and no ARIA, and it keeps working whatever element the text is in; choose it when the design can live with words rising instead of letters. When the letters must move one by one, use the hidden words with the letters under `aria-hidden`: it works on any element, including a paragraph or a block of text in a `div`. The name on the heading is the smallest change if you already use GSAP's SplitText, which writes it for you, but it holds only on a heading, a link or a button.

## Implementation decisions

Hiding the letters is half of each fix. A name or hidden copy on its own, with the letters still exposed, leaves a screen reader two things to read: Chrome names the heading with the words, but reading down the page, the letters are still there, one at a time. Hide the letters with `aria-hidden="true"` on a wrapper or on each word box, never on the heading itself, which would hide the hidden copy too.

Check what your library writes. Splitting.js adds no ARIA. GSAP's SplitText, since 3.13, adds by default (its `aria` option set to `"auto"`) an `aria-label` to the element it splits and `aria-hidden="true"` to every line, word and letter; on a heading that is the third fix above, and on a `p` or `div` it is the failure described there. GSAP's documentation says its automatic labels don't carry links or other elements inside the text, and points to a hidden copy for those. Text with a link inside it is better split into words, or left whole.

The letters' animation itself is another topic: letters that rise or fade in as the page loads or scrolls should stay still when the system asks for reduced motion, as the `prefers-reduced-motion` query does in each snippet above.

## Verify the fix

1. With a screen reader, read the page from the top with the down arrow: the animated heading is read once, as words, not letter by letter and not twice.
2. Open the screen reader's list of headings, and its list of links if a link is split: the entry is the words, as written on screen.
3. In the browser's developer tools, open the accessibility tree and select the heading: its name is the words, with a space between words and none inside them, and the letters are marked as ignored or hidden.

Record the OS, browser and assistive-technology versions, the build, the date, and the actual result of each step. Repeat after the animation or its library changes.

## Limits

This is a starting pattern, not a guarantee for every application. It covers a heading split by a script into letters for an animation, and was checked in Chrome's accessibility tree; other browsers build their trees in their own way, and no screen reader was tested for this guide. Whether a screen reader spells the letters, reads them as sounds, or joins some of them depends on the screen reader, its settings and its speech engine. Text split into lines, for a line-by-line reveal, keeps its words and is not covered here.

---

Get this guide in your coding agent: MCP https://easeweb.dev/mcp (setup at https://easeweb.dev/services/developers)
