Feed

A feed lets users read and skim a stream of articles that loads more as they scroll. An accessible feed carries the feed role and a name, holds named articles that report their position and set size, and declares itself busy while updating.

Social media timelines, streams of news stories, and sets of related products are common examples of feeds. Articles can be added at either end, so the full set is rarely in the page at any one time.

A feed has two parts: a container carrying the feed role, and the articles inside it, each carrying the article role. HTML has no feed element, so the container always takes role="feed", while the native <article> element supplies each article's role.

A feed is a structure rather than a widget. Screen readers stay in reading mode inside it, and the role sets up an agreement between the page and assistive technology. As the reading cursor moves from article to article, the screen reader moves focus with it, and the page scrolls the focused article into view and loads more articles as they're needed. Operation describes the agreement in full.

With this agreement, users can read a stream that keeps growing without leaving reading mode or losing their place. They can also skim it, hearing each article's name and a short description as they move from one to the next.

The feed role is needed only when articles load as users scroll or read through the feed. Otherwise, place the articles one after another in the page, each with a heading, or use one of the patterns listed in Related Patterns.

When to Use

Use a feed when:

Content arrives as a stream of independent items, such as posts, stories, or products, and more items load as users scroll.
The total number of items is unknown, very large, or changes while users read.
Users read or skim the items one after another and benefit from moving quickly between them.

Don't use a feed when:

The set of items is fixed and fully in the page. Place the articles one after another, each with a heading, or use an accordion, tabs, or a carousel.

Examples

Code in this section is meant to demonstrate techniques rather than requirements and lacks features needed in a production application.

Feed of Articles That Loads as Users Read

The feed is a <div> with role="feed", named by the heading above it. Each article is focusable, named by its heading, and described by its summary. The total number of articles isn't known, so every article carries aria-setsize="-1", and its aria-posinset gives its place in the feed. A link after the feed gives Control + End somewhere to go.

Feed HTML

HTML

<h2 id="feed-heading">Latest articles</h2>
<div
  role="feed"
  aria-labelledby="feed-heading"
  aria-busy="false">
  <article
    tabindex="0"
    aria-labelledby="article-1-title"
    aria-describedby="article-1-summary"
    aria-posinset="1"
    aria-setsize="-1">
    <h3 id="article-1-title">
      Designing for keyboard users
    </h3>
    <p id="article-1-summary">
      Why every control needs a visible
      focus indicator.
    </p>
  </article>
  <article
    tabindex="0"
    aria-labelledby="article-2-title"
    aria-describedby="article-2-summary"
    aria-posinset="2"
    aria-setsize="-1">
    <h3 id="article-2-title">
      Writing useful alt text
    </h3>
    <p id="article-2-summary">
      How to describe an image by what
      it's for on the page.
    </p>
  </article>
</div>
<a href="/archive">Browse the archive</a>

The script moves focus between articles with Page Down and Page Up, and past the feed with Control + End and Control + Home. It keeps the focused article in view, and when focus reaches the last article it loads more. The feed is marked busy until the new articles are in place, and the reset runs even when the load fails.

Feed JavaScript

JavaScript

const feed = document.querySelector('[role="feed"]')
let loaded = feed.children.length


// move focus between articles, or past the feed
feed.addEventListener('keydown', (event) => {
  const article = event.target.closest('article')
  let target = null
  if (event.ctrlKey && event.key === 'End') {
    target = focusableBeside(feed, 'after')
  } else if (event.ctrlKey && event.key === 'Home') {
    target = focusableBeside(feed, 'before')
  } else if (event.key === 'PageDown') {
    target = article.nextElementSibling
  } else if (event.key === 'PageUp') {
    target = article.previousElementSibling
  }
  if (target) {
    event.preventDefault()
    target.focus()
  }
})


// keep the focused article in view,
// and load more when focus reaches the end
feed.addEventListener('focusin', (event) => {
  const article = event.target.closest('article')
  article.scrollIntoView({ block: 'nearest' })
  if (article === feed.lastElementChild) {
    loadMore()
  }
})


async function loadMore() {
  if (feed.getAttribute('aria-busy') === 'true') {
    return
  }
  feed.setAttribute('aria-busy', 'true')
  try {
    // fetchArticles() resolves to new article elements
    const articles = await fetchArticles()
    for (const article of articles) {
      article.setAttribute('tabindex', '0')
      article.setAttribute('aria-posinset', ++loaded)
      article.setAttribute('aria-setsize', '-1')
      feed.append(article)
    }
  } finally {
    feed.setAttribute('aria-busy', 'false')
  }
}


// first focusable element after the feed,
// or last focusable element before it
function focusableBeside(element, side) {
  const all = [...document.querySelectorAll(
    'a[href], button, input, select, textarea, [tabindex="0"]'
  )]
  const position = side === 'after'
    ? Node.DOCUMENT_POSITION_FOLLOWING
    : Node.DOCUMENT_POSITION_PRECEDING
  const matches = all.filter((el) =>
    !element.contains(el) &&
    element.compareDocumentPosition(el) & position
  )
  return side === 'after' ? matches[0] : matches.at(-1)
}

Structure and Semantics

A feed is a container with the feed role holding articles, each carrying the article role. HTML has no feed element, so the container is a generic element with role="feed", and the native <article> element supplies the article role. The feed is named for its content, usually by the visible heading that introduces it.

Each article is focusable, with tabindex="0" or tabindex="-1", and takes its accessible name from its own heading through aria-labelledby. Pointing aria-describedby at the article's main content is optional but strongly recommended. Screen readers can then read each article's name and description as users move by article, so users can skim the feed.

The page holds only part of the feed at a time, so each article carries aria-posinset and aria-setsize, and the feed carries aria-busy="true" while articles are being added or removed.

Feed Has Articles

A feed holds its content in articles, and each is a child of the feed carrying the article role. The native <article> element carries the role without an attribute, and articles are what assistive technology moves between when users go from one item to the next.

Gives members the required role

Reported as: No group members with required role

A feed's children must carry the article role.

When the feed's items are generic elements or list items, or sit inside an extra layout wrapper, assistive technology finds a feed with no articles. Screen reader users are told they've entered a feed and then hear its content as unrelated text, with no way to move by article and no position or count.

Render each item as an <article> element, or give it role="article", as a direct child of the feed. Remove any wrapper elements between the feed and its articles.

Severity: Serious

Standard	Success Criterion	Reference
WCAG 2.2	1.3.1 Info and Relationships (A)	Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
EN 301 549	9.1.3.1 Info and Relationships	Same as the WCAG text.

Feed Structure

Everything inside a feed belongs to one of its articles. Users move through a feed by article, so content sitting between articles is skipped, and the agreement between the page and assistive technology covers articles only.

Keeps all content in articles

Reported as: Feed content outside article

All content inside a feed must sit within one of its articles.

When a date separator, a loading indicator, or an end-of-feed message sits directly in the feed, users moving by article step past it. They never hear the date that groups the articles below it, or the message that nothing more will load.

Put each item in its own article, and move content that isn't an item out of the feed, such as a loading indicator, which can sit after it. When an inserted block is an item, such as a sponsored post, make it an article with its own position in the feed.

Severity: Minor

Standard	Success Criterion	Reference
WCAG 2.2	1.3.1 Info and Relationships (A)	Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
EN 301 549	9.1.3.1 Info and Relationships	Same as the WCAG text.

Role

The container that holds a feed's articles carries the feed role, which no HTML element supplies. The role is what keeps screen readers in reading mode, moves focus with the reading cursor, and lets users move article by article, so a container without it is read as ordinary content.

Has the correct role

Reported as: Element has incorrect role

A feed's container must carry role="feed".

When the container has no role, or a role from a related pattern such as list, assistive technology doesn't set up the reading agreement the feed depends on. Screen reader users can't move reliably between articles, and new articles may not load as they read, leaving them at what seems to be the end of the content.

Add role="feed" to the element that directly contains the articles.

Severity: Critical

Standard	Success Criterion	Reference
WCAG 2.2	4.1.2 Name, Role, Value (A)	For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies.
EN 301 549	9.4.1.2 Name, Role, Value	Same as the WCAG text.
Section 508	1194.21(d)	Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text.

Applies role to the correct element

Reported as: Incorrect root element

Sanity check. Evinced checks that the feed role sits on the element that directly contains the articles and carries the feed's name and busy state, not on an element inside it. This check runs on every UI pattern, not only on feeds.

The feed role should sit on the component's outermost element, the one that directly contains the articles, rather than on an element nested inside it.

When the role is on a descendant while the feed's name or aria-busy state is on a wrapper around it, the feed's parts are split across elements. Assistive technology takes the name and the busy state from the element with the role, so values set on the wrapper never reach users.

Put role="feed", the accessible name, and aria-busy on one element, and keep roles and states off any wrapper added for layout.

Accessibility Label

A feed and each of its articles have an accessible name. The feed's name says which stream of content it is, and each article's name comes from its own content, so users moving by article hear which one they've reached.

Names a container that needs one

Reported as: Missing contextual labeling

A feed must have an accessible name that says what stream of content it holds.

When the feed has no name, screen reader users entering it are told only that it's a feed, with nothing about what it carries. On a page with more than one feed, such as a timeline beside a list of trending stories, users can't tell the feeds apart.

Point aria-labelledby at the visible heading that introduces the feed. Use aria-label only when there's no visible heading, and name the feed for its content, such as "Latest news", rather than for its role.

Severity: Moderate

Standard	Success Criterion	Reference
WCAG 2.2	1.3.1 Info and Relationships (A)	Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
EN 301 549	9.1.3.1 Info and Relationships	Same as the WCAG text.

Labels each item from its content

Reported as: Article element not labelled by content

Each article in a feed must take its accessible name from content inside it that identifies it, usually its heading or title.

When an article's name doesn't come from its content, such as a generic aria-label of "Post" or a name taken from a timestamp, users moving by article hear nothing about what the article holds. They have to read each article to judge it, which is the work the feed was meant to save.

Point each article's aria-labelledby at its heading, and add a heading at its start when it has none. Set this in the code that renders one article, so every article gets it.

Severity: Minor

Standard	Success Criterion	Reference
WCAG 2.2	4.1.2 Name, Role, Value (A)	For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies.
EN 301 549	9.4.1.2 Name, Role, Value	Same as the WCAG text.
Section 508	1194.21(d)	Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text.

Articles Accessibility Labels

Every article in a feed has an accessible name of its own, different from the names of the articles around it. Screen readers announce each article by name as users move through the feed, so the name is what users decide by when they skim.

Identifies each member by name

Reported as: Group members missing accessible names

Every article in a feed must have an accessible name.

When articles have no name, screen reader users moving through the feed hear only "article" and its position, over and over, with nothing to tell one from the next. Skimming, the main reason to move by article, isn't possible.

Give each article a name with aria-labelledby that references its heading. When an article has no heading, add one at its start and reference it.

Severity: Critical

Standard	Success Criterion	Reference
WCAG 2.2	4.1.2 Name, Role, Value (A)	For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies.
EN 301 549	9.4.1.2 Name, Role, Value	Same as the WCAG text.
Section 508	1194.21(d)	Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text.

Tells one member from another

Reported as: Group contains duplicate names

No two articles in a feed should share an accessible name.

When several articles carry the same name, such as a repeated headline or the words "New post", users moving by article hear the same name each time. They can't tell which article they're on, or whether they've moved at all.

Name each article from the text that sets it apart, usually its own heading. When articles share a headline, point aria-labelledby at a second element as well, such as the author or the date.

Severity: Serious

This issue is classified as "Best Practice," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

Set Size

Each article in a feed carries aria-setsize, either the number of articles loaded so far or the total number in the feed, whichever helps users more. When the total number isn't known, aria-setsize="-1" says so.

Reports one total for the set

Reported as: Aria-setsize conflicting values

Every article in a feed must declare the same aria-setsize.

When each batch of articles keeps the count that was known when it loaded, users hear the set size change as they move through the feed, from "3 of 10" to "11 of 20", and can't tell which number to trust.

Update aria-setsize on every article whenever articles are added or removed, not only on the new ones. Use the same value on every article: the number of articles loaded so far, the total number in the feed, or -1 when that isn't known.

Severity: Moderate

Standard	Success Criterion	Reference
WCAG 2.2	1.3.1 Info and Relationships (A)	Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
EN 301 549	9.1.3.1 Info and Relationships	Same as the WCAG text.

Carries the total on each item

Reported as: Aria-setsize invalid implementation

aria-setsize should be set on each article, not on the feed.

When the count is only on the feed container, assistive technology never pairs it with an article's position, so users moving by article hear no set size.

Remove aria-setsize from the feed and set it on every article, with the same value on each, alongside aria-posinset. Set both in the code that renders each article.

Severity: Minor

Set Position

Each article in a feed carries aria-posinset, its position in the whole feed, since only part of the feed is in the page at a time. Assistive technology reports the position with the set size, so screen reader users hear something like "4 of 20" and know how far through the feed they are.

Fits each position in the set

Reported as: Aria-posinset is larger than aria-setsize

Each article's aria-posinset must be a whole number from 1 up to its aria-setsize, unless the size is -1.

When an article's position falls outside the set, users are told something that can't be true, such as "12 of 5", and lose track of how far through the feed they are.

Number articles from 1 by their place in the whole feed, not by their index in the batch that loaded them, and derive the position and the size from the same count. When the total number isn't known, set aria-setsize="-1".

Severity: Moderate

Standard	Success Criterion	Reference
WCAG 2.2	1.3.1 Info and Relationships (A)	Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.
EN 301 549	9.1.3.1 Info and Relationships	Same as the WCAG text.

Carries the position on each item

Reported as: Aria-posinset invalid implementation

aria-posinset should be set on each article, not on the feed.

When the position is on the feed container, it describes nothing, and the articles carry none. Users moving by article aren't told where they are in the feed.

Remove aria-posinset from the feed and set it on every article, numbered by its place in the feed. Set aria-setsize on the articles alongside it.

Severity: Minor

aria-busy

A feed sets aria-busy="true" while articles are being added or removed, and returns it to false when the change is complete. While a feed is busy, assistive technology can hold back changes inside it, except in the article the user is reading, and present them as one update when the feed is ready.

Declares itself busy while updating

Reported as: Feed missing aria-busy attribute

A feed must set aria-busy to true before a multi-step update to its articles and back to false when the update ends, whether it succeeds or fails.

When the feed never declares itself busy, articles reach screen reader users one at a time as they land, and articles removed from the other end disappear under someone reading them. When the state is never reset, assistive technology may hold back every later change, so new articles that sighted users can see never reach screen reader users.

Reset the state in a finally block, or another path that runs after a failed load. Add and remove articles only at the ends of the feed, not in the middle.

Severity: Serious

Standard	Success Criterion	Reference
WCAG 2.2	4.1.3 Status Messages (AA)	In content implemented using markup languages, status messages can be programmatically determined through role or properties such that they can be presented to the user by assistive technologies without receiving focus.
EN 301 549	9.4.1.3 Status Messages	Same as the WCAG text.

Disabled

A feed is a structure for reading rather than a control, and it has no disabled state. ARIA 1.2 deprecated aria-disabled on the feed and article roles, so a disabled state belongs only on an unavailable control inside an article.

Never declares a disabled state

Reported as: Component does not support disabled state

A feed and its articles must not declare a disabled state.

When disabled or aria-disabled sits on the feed or on an article, assistive technology may drop it or report the content as disabled. Users who are told the feed is unavailable may skip content they could read, while every control inside it still works.

Remove the attribute. When a control inside an article is unavailable, such as a share button, disable that control.

Severity: Serious

Standard	Success Criterion	Reference
WCAG 2.2	4.1.2 Name, Role, Value (A)	For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies.
EN 301 549	9.4.1.2 Name, Role, Value	Same as the WCAG text.
Section 508	1194.21(d)	Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text.

Disables only elements that support it

Reported as: Element type does not support disabled state

An element in a feed must carry disabled or aria-disabled only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute, as the section intro describes. When a control inside the feed is unavailable, set the disabled state on that control, using an element or role that supports it.

Severity: Serious

Standard	Success Criterion	Reference
WCAG 2.2	4.1.2 Name, Role, Value (A)	For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies.
EN 301 549	9.4.1.2 Name, Role, Value	Same as the WCAG text.
Section 508	1194.21(d)	Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text.

Avoids conflicting disabled states

Reported as: Conflicting disabled values

A feed and its articles must not carry disabled values that conflict.

When the feed or an article carries both disabled and aria-disabled with values that disagree, such as disabled with aria-disabled="false", assistive technology can report a state different from the one the browser applies, on content that has no disabled state to report.

Remove both attributes from the feed and its articles, as the section intro describes. When a control inside an article is unavailable, disable it in one way only.

Severity: Serious

Standard	Success Criterion	Reference
WCAG 2.2	4.1.2 Name, Role, Value (A)	For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies.
EN 301 549	9.4.1.2 Name, Role, Value	Same as the WCAG text.
Section 508	1194.21(d)	Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text.

Keeps disabled off the feed

Reported as: Element does not support the disabled attribute

A feed and its articles must not carry the HTML disabled attribute.

When disabled is set on the feed or on an article, browsers ignore it. Nothing changes for users, and screen reader users hear nothing about content the design may show as unavailable.

Remove the attribute, as the section intro describes. When a control inside an article is unavailable, set disabled on that control.

Severity: Serious

Standard	Success Criterion	Reference
WCAG 2.2	4.1.2 Name, Role, Value (A)	For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies.
EN 301 549	9.4.1.2 Name, Role, Value	Same as the WCAG text.
Section 508	1194.21(d)	Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text.

Relationships

A feed's articles are its children in the DOM, in the order users read them, and that nesting conveys the relationship without any ARIA. When articles load, add them to the feed itself, at its start or its end, rather than rendering them elsewhere and attaching them.

aria-owns

A feed renders its articles inside it, so nothing in a feed needs aria-owns. When articles rendered elsewhere are attached with aria-owns, the DOM, focus, and scrolling keep the original structure, and moving focus from article to article no longer follows the feed.

Avoids aria-owns

Reported as: Avoid aria-owns

General check. Evinced checks that the feed doesn't use aria-owns to claim its articles or other elements as its children. This check runs on every UI pattern, not only on feeds.

A feed should not use aria-owns to restate articles it already contains in the DOM.

When aria-owns lists the feed's own articles, the attribute and the markup record the same set twice and agree only until articles load or are removed. When the attribute isn't updated, it wins in the accessibility tree, so users get articles that are missing or out of order.

Remove aria-owns from the feed and let the DOM state which articles it holds.

Owns only conforming roles

Reported as: Invalid aria-owns values

General check. Evinced checks that every element a feed claims with aria-owns has the article role. This check runs on several UI patterns.

When a feed uses aria-owns anyway, each element it references should be an article.

When the feed owns an element that isn't an article, the feed's articles no longer match its set size and positions, and screen reader users moving from article to article reach content the feed doesn't present as one of them.

Render each article inside the feed in the DOM and remove aria-owns, as the section intro describes.

Operation

Screen readers handle most movement through a feed in reading mode. As the reading cursor moves from one article to the next, the screen reader moves focus to that article, and it provides keys that move to the next or previous article and past either end of the feed.

The page does the rest: it scrolls the focused article into view, loads more articles before focus reaches either end of what's loaded, and removes articles far from focus when it needs to.

Instead of loading articles as focus nears the end, a page can end the loaded set with an article holding a button that loads more.

Feeds have no established keyboard convention, so provide keys for users who don't have a screen reader's article navigation. When focus is inside the feed, Page Down moves focus to the next article and Page Up to the previous one. Control + End moves focus to the first focusable element after the feed, and Control + Home to the first focusable element before it.

Handle these keys in a keydown listener rather than with the deprecated keypress event, and document them where users can find them. Nothing else tells users the keys exist.

A feed nested in an article, such as a feed of comments, is reached with the Tab key or a key of its own, such as Alt + Page Down. Control + End then moves focus out of the nested feed to the next article in the outer one.

Event Listener Type

When script in a feed responds to keys, it listens for keydown or keyup. The keypress event is deprecated, and browsers don't fire it for many keys, including the arrow keys, Home, End and Escape.

Avoids the keypress event

Reported as: Deprecated keypress listener

A feed's key handling should use keydown or keyup, not keypress.

When a handler listens for keypress, keys the browser doesn't send through that event go unanswered, and keyboard users find the feed ignoring keys it's meant to respond to.

Replace each keypress listener with a keydown listener, and read the key from event.key.

Severity: Minor

FAQ

Which WCAG success criteria do the feed issues relate to?

Most relate to 1.3.1 Info and Relationships or 4.1.2 Name, Role, Value. 1.3.1 covers the feed's name, its articles and the content between them, and the position and set size each article reports. 4.1.2 covers the feed role, each article's name, and the disabled state. Declaring the feed busy while it updates relates to 4.1.3 Status Messages.

Telling articles apart by name, and setting position and size on the articles rather than on the feed, map to no WCAG success criterion and are best practices.

Why are some feed issues marked as Critical and others as Minor?

Severity reflects how much an issue gets in users' way. Critical issues stop users outright:

A container without the feed role
Articles with no accessible name

Serious issues confuse users though they can still read the feed:

Articles that share a name
Feed children without the article role
A feed that never declares itself busy
A disabled state on the feed or an article

Moderate issues leave users unsure which feed they're in or where they are in it:

An unnamed feed
A position larger than the set size
Articles that report different set sizes

Minor issues are smaller obstacles:

Content between articles
An article name that doesn't come from its content
Position or set size on the feed rather than on its articles

The aria-owns checks and the check on where the feed role sits carry no severity: Evinced reports them as general and sanity checks.

Accordion: stacked sections of content, each shown or hidden by its heading
Tablist: panels of content, one shown at a time, chosen from a set of tabs
Carousel: a set of slides of content, shown one or a few at a time

When to Use

Examples

Feed of Articles That Loads as Users Read

Structure and Semantics

Feed Has Articles

Feed Structure

Role

Accessibility Label

Articles Accessibility Labels

Set Size

Set Position

aria-busy

Disabled

Relationships

aria-owns

Operation

Event Listener Type

FAQ

Related Patterns

Recommended Reading