Semantics of labelling elements that contain data

One of my colleagues is currently working on an ‘Arrivals’ widget/component to be included on a dashboard. Within the widget is to be an ‘Intended Arrival Date’ alongside an actual date.

At the moment, ‘Intended Arrival Date’ is contained in a <div> element with a class attribute of field-header on it. To me, that class name suggests that the element ought to have been a <h1> , <h2> , or whatever, but that doesn’t feel quite right, as it’s actually a form of label directly associated with the date alongside it. <label> of course, should be associated with an <input> so that’s not right either.

For accessibility reasons as much as anything, I’d like to that ‘Intended Arrival Date’ to be tied somehow to the date it’s related to, other than by proximity. Is there way of marking them up in such a way with HTML that I’m missing?

Have you looked into BEM notation? BEM stands for “Block Element Modifier” and is pretty much a spec for how to label elements with CSS classnames given their relation and responsibility. I think this may be related to what you want to achieve in that you would have say a <div> that is labeled with a class like intended_arrival and then the arrival date itself would be intended_arrival__date. Notice that it shares the first half of the class name with the parent (the block) but has a double underscore to show that this element is date belonging to that block.

But in short it sounds like you could call the entire element intended arrival date and mark its children as various derivatives of that.

You can read more about the naming conventions of BEM at their official site.

Having had a very quick look at the BEM website, it seems to me that it has nothing to do with accessibility. It’s mostly about ensuring no duplication of CSS class names on large complex websites.

My approach in this case would be to have the ‘widget’ as a <section> element (with border) and inside that an <h2> or whatever for ‘Intended Arrival Date’ together with a <p> element for the date itself. I expect that would be OK for assistive technology. Anyone disagree?

1 Like

The ‘time’ element can be used for dates so may also be helpful here.

I also believe that ‘aria’ labeling can create relationships between elements to aid accessibility.

Of course there are also choices with an HTML table for explicit relationships between data or a dl list.

It’s often hard to decide especially without seeing the whole thing as normal html may also suffice.


I think data in HTML should be in either tables or lists, depending on context.
Lists for one dimensional list of data, tables for a two dimensional matrix of data.
The special case being the <dl> where each item in the list has its own label.
It’s really putting in practice Paul’s comments.
So as a table:-

         <th>Intended Arrival Date</th>
         <th>Actual Date</th>
         <td><time datetime="2021-08-07">7th August 2021</time></td>
         <td><time datetime="2021-08-03">3rd August 2021</time></td>

Or a DL:-

   <dt>Intended Arrival Date</dt>
   <dd><time datetime="2021-08-07">7th August 2021</time></dd>

   <dt>Actual Date</dt>
   <dd><time datetime="2021-08-03">3rd August 2021</time></dd>

I understand assistive technology struggles with tables,

I believe it depends on whether or not the table has been correctly structured. This article is several years old now, but still relevant.


There’s a similar one here also.

Tables are very accessible to assistive devices (as far as data is concerned) if they are structured correctly and the relationship between row and column is maintained effectively.

Things can soon get out of hand though if rows and columns are split and the relationship between headers and columns are mis-managed which is probably where the mis-conception comes from

Simple data tables actually need no extra work apart from suitable th tags in the header and corresponding td tags in the body.

Of course using tables for layout completely breaks accessibility but when used for data they immediately become more accessible than any other html elements that try to do the same job with regard to data information.

I’m not saying that a data list (dl) could not be used in this situation either as semantics are often up for debate but assistive technologies have long had a good relationship with properly formatted table data.


Thanks to everyone for the replies. Having read through those, I’ve concluded that the <dl> element is the way to go. I don’t see this widget ever containing enough to want make use of a <table>. I think what finally convinced me of the efficacy of the <dl> was this line on its MDN page.

Common uses for this element are to implement a glossary or to display metadata (a list of key-value pairs).

The key-value pair relationship being exactly what I wanted to achieve. I’d like to make a couple of tests with a screen reader, but I’ve a feeling it’ll do the trick.


Considering a screen reader will announce a <dl> element as being a “list”, “definition list” or “description list” (reference), I still think an <h2> or whatever heading tag and a <p> element is preferable. I understand the use of a heading tags help users of screen readers.

Having only a date in a paragraph would be a very short paragraph but does that matter? I think a screen reader will read that our more satisfactorily than a <table> or <dl> element.

Certainly use of the <time> element within a <p> element could be helpful.

This Ben Myers article popped up in my Twitter feed today. It does a decent job of outlining the possible application of the <dl>, <dt> and <dd> elements. Very well explained I thought.


Yes, that’s an excellent article.

I note in the last example (link) the heading “Kobold” is <h1> before the <dt> description list starts. For accessibility, I think your widget should have a similar heading.

If I understand your original post correctly, you want your widget to display only “Intended Arrival Date” as a heading followed by the date. So for me the use of a description list is unsuitable. Also you don’t really want screenreaders announcing it as a “list”, “definition list”, “description list” or “table”.

I think it would be appropriate to use <dl> after a heading “Arrival” followed by more than one name-value pair such as with decription terms “Date”, “Airport” and “Flight Number”.

For me, considing how a screenreader would find and read out the information is more important than erudite theoretical semantics.

I really miss @Stomme_poes for her knowledge of screen readers (and other accessibility issues). frown

My understanding is that screen readers will read out headings as an aid to navigation; you can move through sections of a page via the headings. I’d be concerned that using them in this context would add a lot of clutter and make navigation more difficult.

Of course, the best option would be to contact actual screen reader users and get their input.


As this is described as a “widget” and the date is not being inserted within a block of text, I think it should have a heading tag of appropriate level to aid navigation for users of screenreaders. I don’t see that it would add any clutter at all. A user may well wish to find the intended arrival date without having to have a lot of other content read out. An appropriate heading will help not hinder screenreader users.

We don’t know what other content there is on this page but I suggested in post #3 that the widget should be a <section> element, albeit a small one.