Re-imagining details/summary design


I have been questioning the current design on the details/summary feature for a while. Its design seems overcomplicated and inflexible. Am wondering if there is still time to reconsider the design, making it more flexible, and at the same time making implementation simpler…

There is a rough spec for an alternative and demos of a custom element based on the spec.


I have not found any problem with <details>/<summary>. As consultants, we use them in production websites regularly, usually with tiny polyfills for older browsers.

The only problem is styling them, but that is taken care of in nonstandard ways by vendor-specific pseudo-elements, and besides it is a problem inherent to basically any nontrivial HTML element.


I think I am where @domenic is here - what is the difficulty/inflexibility of which you speak? Is it that it has to be parent/child relationship or certain style or script things are difficult? Can you expand?


I haven’t been able to deploy any details/summary usage in a production app either. It just tricky to style correctly.

The direct parent child relationship makes it hard. Typically the markup for implementing this kind of thing looks like:

<div class="details-container">
  <p>Inline row with text, but not the target itself <span class="details-target">...</span><p>
  <div class="details-contents">
    <p>Some extra info</p>

Heres some places on that I’d like to be able to use details/summary for:


It does seem like it is better if we could make something a little looser with default styling that it was easier to enhance or even supersede… An accordion, for example is just a stack of these right relationships really… I’ve seen disclosures that pop out or fade in or slide down - all sorts of stuff really. It’s tricky (like label/idref) in terms of styling because they can be in completely different parts of the tree, but they have conceptual relationship that’s important to maintain none the less.


right and that is what the disclosure-button example does, it strips the feature down and makes it easier to deploy. any element can become the equivalent of the details element simply by referencing it from the disclosure control. The disclosure control can be a child of most any element and by styled anyway easily. I am not overly serious about changing the current html feature. I think its just a bit of a mistaken addition as the functionality can be provided easily and simply by other means. details/summary doesn’t add a lot, if anything. The only advantage to details/summary is that when implemented in all browsers it won’t require JavaScript. It should also be noted that while there are implementations, there are no conforming implementations as the interaction behaviour and specced shadow DOMminess of the interactive bits as implemented are at odds with the spec.


It would have been better to create an accordion element, reuse Heading tags as the click targets, and let developers link together a given heading and matching content element within the containing tag using an attribute that specifically targets it. For instance:

  <h3>Title 1</h3>
  <section>Content 1</section>
  <h3 for="content-2">Title 2</h3>
  <section>Content X</section>
  <section name="content-2">Content 2</section>

In the above example, not using for/name targeting would mean a user’s click/touch on a heading will apply an active state to both the heading an the next sibling element. If you used the targeting mechanism shown in the Title 2 example, you could associate the active state toggle of a heading with any element inside the container.

This would provide people with far more extensibility, and solve many more of the common cases this sort of element is generally intended for.


Why set the hidden attribute? The aria attribute is selectable with CSS and in my mind semantically better. Why not just provide default style display:none or size 0/overflow hidden on it and then you can easily add effects, etc via css


Issue here is that the heading semantics are overriden by it function as a button. see


Because hidden is the semantic marker for hidden content. why use aria-hidden and then apply a style, when hidden does both?


Tried responding to this via mail, but perhaps that doesn’t work yet… In either case, will repost my comments here (and expand a bit):

…Because if i want to define how it becomes hidden (a css animation to slide it shut or offscreen perhaps) then i have to fight hidden. Am I doing it wrong? It feels weird debating this with you Steve since you are editor on both of the relevant documents - so I’m just going to share my perspective and say “why is that wrong, because even with the documents - it feels right to me.”

As an illustration, I’ll to point to input type=hidden – generally speaking this is where the idea originates and here it is fundamentally data for processing that has no business ever being shown to a user (but that’s a different thing)… You could use the global hidden attribute for similar reasons - something purely technical… Beyond that, the act of hiding seems like display or accessibility which seem better handled with CSS and Aria, respectively. This same notion this has always seemed to jive in my mind with the HTML spec which states

The hidden attribute must not be used to hide content that could legitimately be shown in another presentation. For example, it is incorrect to use hidden to hide panels in a tabbed dialog, because the tabbed interface is merely a kind of overflow presentation — one could equally well just show all the form controls in one big page with a scrollbar. It is similarly incorrect to use this attribute to hide content just from one presentation — if something is marked hidden, it is hidden from all presentations, including, for instance, printers.

This whole section of the spec, in fact, seems to me to speak of the difference between something that is actually hidden for practical reasons by its nature (for example, a chunk that is maintained via script, never intended to be shown) vs something that is purely about style - it cites examples like a canvas element offscreen, etc. It also states that using CSS you should be able to override the display nature.

Aria’s attribute doesn’t re-invent, it actually better expresses. “Expanded” is what you are trying to express here and it has no conflict that I can see with the specs at all. In fact, in different UIs you might choose to always display them expanded, make them into clickable links which display the contents as a “page” or in some “main” area (think ember/angular), animate them opened and closed, etc… But mostly all of them work with the idea of something ‘expanded’ better than ‘hidden’ imo.


hey I am not married to the use of hidden, if you want to code an alternative method and send a pull request will be happy to merge :slight_smile:

I do tend to agree with your arguments re hidden and consider in retrospect its use in the context of the disclosure element as sub optimal


btw i don’t agree with this (in the spec) but don’t think its important enough to change/fork


I’d love to send a pull – to do so, I have some questions though. In the component right now you are setting style attributes as well as the hidden attribute (why?) - but from this element, I’d like to know who controls it. Let me explain a use case… Let’s say I have a panel which is controllable via a standard title oriented expander right above it – but I also have something elsewhere in the UI, a notification or something where I want to draw their attention. It’s entirely plausible that they BOTH control the SAME element, at which point it seems they would potentially be in disagreement. I’m trying to figure out from an accessibility standpoint how this would work - it seems that 1 target might have many controllers/sources - so it makes the most sense for the target to store the state… Certainly from a styling standpoint, it is the details element, not the summary that is expanded if you see what I mean - but reading the code and the Aria spec, it seems that it is the button itself which is supposed to contain the expanded attribute - I’m having trouble reconciling how that works or could be useful if we need to tie together helpful APIs (maybe) and CSS (definitely)


aria-controls can take a space delimited list of id refs. In terms of the disclosures owned element you could use aria-owns. When you say ‘draw attention to’ for whom? The usual pattern for notifications that are displayed and visually apparent is to use aria-live on the notification container, so the content of the container will be announced by SR’s when displayed. so this does not need to be associated using controls.


its the button because it controls the state of the controlled content. Also from a practical perspective the aria-expanded state needs to be on a focusable element so that it is communicated to the user. Current user experience:

User focuses on button using a screen reader. label (text)/role(button) and state (collapsed) is announced. User activates button label (text)/role(button) and state (expanded) is announced.

For SR’s that support aria-controls - that the button controls something is announced and a keystroke to move to the controlled element is provided.

Also note some acc APIs provide access to reverse relationships. For example Iaccessible 2 (used by firefox/chrome) aria-controls hooks into controllerFor which has a reverse relation property controlledBy


No longer sets hidden, just display value.


So OK there you mean the <span class="details-target">...</span> part is the disclosure control, and you’re saying that shouldn’t have to be a direct child of the same element (<details>) that contains the contents that gets shown/hidden (<summary>)?

If so, I think @SteveF’s alternative proposal would handle that case.


This is exactly what w3c-disclosure does, see code example.

 <!-- can be anywhere in DOM -->
<button is="w3c-disclosure" controlfor="x-id" />

 <!-- can be any element -->    
    <div id=x-id>...


I see the problem now; thanks Steve and others.

My general feeling is that trying to put interactive widgets into the HTML standard has not been a rousing success. Largely this is because there has been no good story for styling or customizing them. (Who wants to use the super-ugly <input type="date"> that ships with Chrome?) The introduction of custom elements provides a way forward for such things, with the promise that in the future if something becomes so ubiquitous that almost everyone is shipping it (like jQuery is today), we can start rolling them back into HTML. And in the meantime, we’ll be figuring out the story for styling shadow DOM and the like.

So yeah, things like w3c-disclosure are probably the way to go for now.