details-summary

Details + summary HTML elements with better style.

See a live demo

Contents

• Install
• Example
• API
  • ESM
  • Common JS
  • Attributes
  • Events
• CSS
  • Import CSS
  • Customize CSS via CSS variables
• Use
  • JS
  • HTML
  • pre-built

Install

npm i -S @substrate-system/details-summary

Example

Tag name, details-summary is exposed as .TAG on the class.

import { DetailsSummary } from '@substrate-system/details-summary'
import '@substrate-system/details-summary/css'

document.body += `
  <${DetailsSummary.TAG}></${DetailsSummary.TAG}>
`

<details-summary duration="400">
    <details>
        <summary>What is this?</summary>
        <div class="details-content">
            This is a details/summary web component with smooth animation.
        </div>
    </details>
</details-summary>

API

This exposes ESM and common JS via package.json exports field.

ESM

import '@substrate-system/details-summary'

Common JS

require('@substrate-system/details-summary')

Attributes

default-open

Boolean attribute. When present, the <details> element will be open by default on viewports wider than 990px.

<details-summary default-open>
    <details>
        <summary>Open on desktop</summary>
        <div class="details-content">This starts open on desktop.</div>
    </details>
</details-summary>

duration

Number (milliseconds). Controls how long the open/close animation takes. Defaults to 300.

<details-summary duration="500">
    <details>
        <summary>Slow animation</summary>
        <div class="details-content">This takes 500ms to open or close.</div>
    </details>
</details-summary>

Events

This element emits four events whenever it opens or closes.

Non-namespaced events

Event	Fired when
open	The element finishes opening
close	The element finishes closing

Namespaced events

Event	Fired when
details-summary:open	The element finishes opening
details-summary:close	The element finishes closing

All events bubble and are composed. Each event carries a detail.details property that references the inner <details> element that triggered the event.

const el = document.querySelector('details-summary')

// non-namespaced
el.addEventListener('open', ev => {
    console.log('opened', ev.detail.details)
})
el.addEventListener('close', ev => {
    console.log('closed', ev.detail.details)
})

// namespaced
el.addEventListener('details-summary:open', ev => {
    console.log('opened', ev.detail.details)
})
el.addEventListener('details-summary:close', ev => {
    console.log('closed', ev.detail.details)
})

Events bubble, so you can also listen on a parent element. Use event.detail.details to get the <details> element that triggered the event:

document.addEventListener('details-summary:open', ev => {
    const details = ev.detail.details  // the <details> element that opened
    console.log('a details-summary opened', details)
})

CSS

Import CSS

import '@substrate-system/details-summary/css'

Or minified:

import '@substrate-system/details-summary/min/css'

Customize CSS via CSS variables

Variable	Default	Description
--details-summary-border-color	0, 0, 0	RGB value for the bottom border color
--details-summary-padding	1rem	Padding for the summary and content
--details-summary-font-weight	600	Font weight of the summary text
--details-summary-font-size	16px	Font size of the summary text
--details-summary-transition-speed	0.3s	Speed of the icon rotation and content fade transitions
--details-summary-content-color	#444	Text color of the details content

details-summary {
    --details-summary-border-color: 100, 100, 200;
    --details-summary-padding: 0.75rem;
    --details-summary-transition-speed: 0.5s;
}

Use

This calls the global function customElements.define. Just import, then use the tag in your HTML.

JS

import '@substrate-system/details-summary'

HTML

<div>
    <details-summary></details-summary>
</div>

pre-built

This package exposes minified JS and CSS files too. Copy them to a location that is accessible to your web server, then link to them in HTML.

copy

cp ./node_modules/@substrate-system/details-summary/dist/index.min.js ./public/details-summary.min.js
cp ./node_modules/@substrate-system/details-summary/dist/style.min.css ./public/details-summary.css

HTML

<head>
    <link rel="stylesheet" href="./details-summary.css">
</head>
<body>
    <!-- ... -->
    <script type="module" src="./details-summary.min.js"></script>
</body>