Source Order Matters

Strawberry, balsamic, black pepper sorbet
A picture of my strawberry, balsamic, black pepper sorbet, which makes sense later in the post and because my blueberry sorbet didn’t come out so well.

CSS is providing newer and more complex methods of laying out your pages. Given the multiple form factors a responsive site has to support, it makes sense that developers want easy ways to structure the layouts that aren’t all floats, clears and position: absolutes.

Regardless of how you want your layout to appear in a browser, you must keep in mind that a clear HTML structure is important to search engines. Sorry, while the bit about search engines is true, it’s not really what I consider important, but it is more likely to get some people to pay attention.

What I consider important are users of screen readers or any kind of assistive technology that allows a user to navigate a page by regions (typically by the Tab↹ key), as well as sighted keyboard users.

WCAG Conformance

WCAG isn’t the final word in making things accessible, but it is the baseline. As such, technique C27, making the DOM order match the visual order, is a good to one to know. It applies specifically to Success Criterion 1.3.2 (Meaningful Sequence) and Success Criterion 2.4.3 (Focus Order). Each of these is Level A, which means they are necessary to satisfy for even the lowest level compliance.

The technique offers some context for how failure to maintain consistent source order can be confusing to users:

This could be due to the user switching off the author-specified presentation, by accessing the content directly from the source code (such as with a screen reader), or by interacting with the content with a keyboard. If a blind user, who reads the page with a screen reader that follows the source order, is working with a sighted user who reads the page in visual order, they may be confused when they encounter information in different orders. A user with low vision who uses a screen magnifier in combination with a screen reader may be confused when the reading order appears to skip around on the screen. A keyboard user may have trouble predicting where focus will go next when the source order does not match the visual order.

That might be a little too much to quickly parse, so let me try…

An Attempt at an Example

Given the average developer’s love of using lists (ordered or otherwise) for everything on a page (assuming he or she has outgrown divs), let’s consider what happens when you use a list in your markup and then style it using a grid.

In the case of an ordered list, like a set of instructions, the order is very important and the browser will convey that to assistive technology. Borrowing a bit from Greg Whitworth (stealing, really), imagine a (very minimal) recipe:

  1. Puree the blueberries
  2. Push through a sieve to extract the skins
  3. Put in ice cream maker for 20 minutes

Visually as a two-by-two grid the CSS could cause that to flow top to bottom or left to right. Regardless of how it looks on screen, the order of the list must be retained. If a developer who is struggling with the CSS tries to just fudge the HTML (because the source order doesn’t matter for CSS grid or flexbox), you might get this list:

  1. Puree the blueberries
  2. Put in ice cream maker for 20 minutes
  3. Push through a sieve to extract the skins

I can tell you that this sorbet will not come out well.

The Takeaway

Code your pages so the HTML source linearizes well and the content makes sense without styles. When you do add visual styles, try to get them to conform to the source order as much as possible.

CSS grid and flexbox can make it tempting to render something completely differently than some bad structure you might inherit, but take a moment to think through its impact first.

What Did It This Time?

Mozilla Hacks posted a great article on CSS grids that had one statement that caused the hairs on the back of my neck to stand up and panic:

One aspect of it is that the ordering of the content in the HTML markup isn’t important anymore.

My fear was that developers would read that and take it to mean that the structure of their HTML was now no longer a concern. I wasn’t the only one who had that reaction. It came up on the CSS Working Group conference call this morning when Brian Kardell asked the question:

bkardell_: Effectively I guess…do we need to strongly pusht he same sort of understanding to authors that we’re pushing to the tooling? Even just today Moz hacks posted an article saying that the order of content in HTML markup isn’t important anymore

It also came up on the Gitter w3c/a11ySlackers channel. This is good because it means people are paying attention.

By the time I started this post, Mozilla Hacks approved comments from Dylan Barrell, fantasai, and Greg Whitworth and subsequently updated the post with this:

One aspect of it is that the visual order of elements on the page is decoupled from the order of elements in the markup. That’s important because on a page the source order is used for things like speech and tab navigation, so CSS Grids allow you to optimize the markup for accessibility without compromising your ability to manipulate the visual result.

Given that the original post isn’t about accessibility, I think it’s fair to leave it at that. But since you are here, bear in mind C27 above.

Update: October 25, 2015

I’ve just written a post, HTML Source Order vs CSS Display Order, which shows how different CSS layout methods can affect visual display. You can consider them examples for this article. Below are some images showing the effects of Flexbox and Grid.

CSS Flexbox tab order in Chrome 45. CSS Flexbox tab order in Firefox 41.
The first image is an animation of Chrome 45 tabbing through flex items. The second is an animation of Firefox 41 tabbing through flex items.
CSS Grid tab order in Internet Explorer 11. CSS Grid tab order in Firefox 41 with the flag enabled.
The first image is an animation of Internet Explorer 11 tabbing through CSS Grid items. The second is an animation of Firefox 41 tabbing through CSS Grid items. The flag has been enabled, but as you can see support is pretty poor.

Update: July 22, 2017

Rob Dodson responds to questions about content order in his most recent video at YouTube, Does reordering content affect accessibility?, which I have embedded below.

I also embedded this video in my slightly more recent post, HTML Source Order vs CSS Display Order.

Update: March 24, 2019

Update: April 13, 2019

I have created a bookmarklet to test reading order (not focus order). It is not perfect, but until accessibility checking tools can build something into their own tests this might still be handy for some of us.

Update: May 11, 2019

Manuel Matuzovic has an ongoing series about CSS Grid and accessibility. In The Dark Side of the Grid (Part 2) he talks about the risk of changing DOM order, mostly leaning on tab order as a proxy.

Make sure that visual order is comprehensible and that it matches DOM order as good as in any way possible.

Update: June 2, 2019

Sarah Drasner released a tool to prototype grid layouts. She included a warning about reading order, though I doubt most visitors will note it. I called it out because all these tools need to state it and ideally make it obvious.

Update: June 4, 2019

Rachel Andrew posted Grid, content re-ordering and accessibility today, where she notes she is starting to encounter ordering issues in the wild:

For those working on a11y and CSS, this has been discussed before, however given the things I am starting to see in the wild, I think this has to have some urgency behind it.

If you have been reading my blog, then you know I have seen this in the wild for a while (as the date of this very post indicates). Accessibility tends to be the canary in the coal mine for new technologies, spotting issues well before they impact a larger audience. The more voices raising this issue the better.

Update: October 15, 2019

I made a pitch video:

If that video is too large or otherwise chunking, view it at YouTube, which does a better job with streaming. It has the same captions. Links to the screen shots and resources mentioned in the video are available at Smashing / Web We Want Video Pitch.

Update: September 9, 2020

The Source order viewer settings in the dev tools.
In Edge 86, press Ctrl + Shift + I to open the dev tools, then F1 to open the settings, arrow down twice to Experiments, then Tab to and select “Source order viewer”.

Microsoft has added a source order view to Edge 86 which, at the time of this writing, is in the Dev channel and must be enabled. It also lives in Chromium, so could do this in Chrome as well if you prefer. I give a bit more context and more screen shots in my post Source Order Viewer in Edge 86.

Give it a shot and see if it makes it easier when evaluating WCAG Success Criterion 1.3.2 Meaningful Sequence (A).

If you do not use a Chromium browser, remember I have a Reading Order Bookmarklet that does the same thing (and was the basis of this browser feature). Firefox appears to still be working on the feature request as well.

Update: June 3, 2022

WebAIM has a new post, Flexbox and the Screen Reader Experience, which provides a better visual for a recipe than I do in this post.

What the WebAIM post addresses applies to more than flexbox, however. CSS grid, floats, and absolute position are all just as risky, as I demonstrate in examples on my own post about source order and display order.

Update: December 27, 2022

The CSS Display Module Level 3 Editor’s Draft has added a section to discuss display order, where it proposes layout-order and reading-order CSS properties. These are scoped to CSS flex and grid only.

There is a section on re-ordering and accessibility that, at a glance, appears to take into consideration accessibility feedback I left in June. I encourage accessibility practitioners and users to give their feedback.

Update: May 8, 2023

Two weeks ago I attended CSS Café to hear Rachel Andrew present When New CSS Features Collide: Possibility and Complexity at the Intersections, which was about reading order in the context of CSS flexbox and grid.

Rachel linked to Solving the CSS layout and source order disconnect, posted April 12 on the Chrome developer blog. While I had not seen the post until the live stream, it looks to cover similar properties I linked in my last update (December 2022). The GitHub issue where this is being tracked appears to be the same one that has the feedback I left in June.

To distill it down to the simplest bits, the proposed solutions are:

These two properties only work in the context of flex and grid. They do nothing for floats or absolute positioning.

Update: February 25, 2024

Chrome has announced its intent to prototype CSS reading-order-items.

The explanation (emphasis at the end mine because boy do I twist up inside at such blanket statements that feel like the re-wordings of tech bros pitching to funding sources in every episode of Silicon Valley):

We want to allow the content displayed on a screen to be navigated visually and not always follow the DOM order navigation. To do this, we need to add support for grid and flex reading orders. This helps for keyboard navigation and screen to speech tools; which help make the web more accessible for all.

Read the latest version of the reading-order-items property in the CSS Display Module Level 4 Editor’s Draft.

The issues I linked previously are now mostly dormant. The latest discussions are:

Weigh in as you see fit.



Thanks for posting this. I wrote up my thoughts recently about Grid Layout, specifically in terms of the issue of flattening out of mark-up in order to make everything a child of the grid. It’s for this reason I believe that subgrid is an important part of the spec.


[…] The future of layout with CSS: Grid Layouts but remember that Adrian Roselli told you that Source Order Matters. […]


[…] Source Order Matters – Adrian Roselli – […]


[…] […]

Дайджест интересных материалов из мира веб-разработки и IT за последнюю неделю №177 (14 — 20 сентября 2015) -; . Permalink

[…] month in my post Source Order Matters I wrote about why we need to consider how the source order of the HTML of a page can affect users […]


super thank you for your tips.


Isn’t it the case that the tabindex attribute may be deployed within the markup to explain to the user-agent the order in which elements should be interacted with using keyboard navigation, assistive technologies etc.?

See: tabindex (MDN)

Alan L; . Permalink

Ohhh. I see you’ve already covered this here:

Alan L; . Permalink
In response to Alan L. Reply

Considering I failed to mention tabindex at all in my post, I could have done a better job of pointing it out as a non-option. Also worth noting that tabindex changes focus order, not reading order. A screen reader user, for example, experiences the page in DOM order and is only affected by tabindex if they press Tab to navigate. Most screen reader users move through a page with arrow keys and other keys.

Leave a Comment or Response

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>