Add Responsive-Friendly Enhancements to <details> with <details-utils>
@zachleat/details-utils
A collection of utilities to progressively enhance <details> with new features
Demo GitHub271 npm- Popularity
- npm52k
cdn347k
- Versions
- 5 versions in3.0.0
- Audit
-
0 reports
0 deps - Issues
-
3
2 - PRs
-
0
2
I use <details>. I use <details> a lot. It is one of my favorite HTML elements.
Over time I’ve collected a bunch of add-on utilities to enhance <details> with new features and functionality. They’ve been super useful in a bunch of long-standing production implementations at Netlify:
- 11ty.dev Eleventy Docs sidebar menu
- netlify.com masthead navigation
- The shared masthead navigation (across various tech-stacks) on Netlify Community (Vue/Eleventy), Remotely Interesting Podcast (Eleventy), Netlify Explorers (Next.js), Netlify Swag (Gatsby.js), and Netlify Answers (Discourse).
- jamstack.org masthead navigation
- Your Year on Netlify wizard steps
- (and probably more?)
I’ve decided to finally package those <details> helpers up and formally release them as a web component!
<details-utils>
<details-utils>
<details>…</details>
<!-- you can have one or more <details> elements in here -->
</details-utils>At time of writing, this web component adds five new responsive-friendly enhancements to one or more <details> elements nestled inside:
- Force open/closed
- Click outside to close
- Close on
esc - Animate open/closed
- Toggle root element
class
Force open/closed
In this example, the <details> is forced open when viewport is wider than 48em.
<details-utils force-open="(min-width: 48em)" force-restore>
<details open>…</details>
</details-utils>I’ve gotten a lot of mileage out of the above example, specifically to drive navigation that is always visible at a certain breakpoint (think a collapsible menu at small viewport versus sidebar, e.g. 11ty.dev/docs/).
Alternatively, force-close is also available. The optional force-restore attribute will restore previous state when the force-open or force-close media queries do not match.
The media query is optional, and using it as a bare attribute allows control of the state pre and post JavaScript.
<!-- closed without JS, open with JS -->
<details-utils force-open>
<details>…</details>
</details-utils>
<!-- open without JS, closed with JS -->
<details-utils force-close>
<details open>…</details>
</details-utils>Click outside to close
If you click anywhere on the document (outside of the <details> content), the <details> will be closed. This is useful when you want to absolutely position the <details> content (maybe to make a little custom dropdown 😱)
<details-utils close-click-outside>
<details>…</details>
</details-utils>You can scope this with a media query as well:
<details-utils close-click-outside="(min-width: 48em)">
<details>…</details>
</details-utils>Add your own bonus close button inside of the content (to complement <summary>):
/* Hide button without JS */
details-utils:not(:defined) [data-du-close-click] {
display: none;
}<details-utils close-click-outside>
<details id="my-details">
<summary>…</summary>
<button type="button" aria-controls="my-details" data-du-close-click>Close</button>
</details>
</details-utils>Close on esc
Closes the <details> when the esc key is hit on the keyboard. Media query is optional.
<details-utils close-esc="(max-width: 767px)">
<details>…</details>
</details-utils>Animate open/close
<details-utils animate>
<details>…</details>
</details-utils>Animates the height of the content when opening and closing the <details>. Ignored automatically if (prefers-reduced-motion) is detected.
Just a full disclosure, the configuration around this one is pretty limited (re: easing and timing). Also this doesn’t support media query scoping yet (not for any technical reason, just haven’t run into this use case yet). Open to contributions here!
Toggle class on root element
<details-utils toggle-document-class="my-class-name">
<details>…</details>
</details-utils>Adds a class to your <html> element when the <details> is open and removes it when the <details> is closed.
Enjoy!
Wiring up and combining each of these enhancements to <details> really can go a long way in building a lot of complex user interface elements in a pretty straightforward way. In my humble opinion, the super long list of things I’ve built using this is proof of that. I hope you can get some useful mileage out of them too!
