details-summary

Details + summary HTML elements with better style.

See a live demo

• 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>

disabled

Boolean attribute. When present, the panel is locked — it can neither be expanded nor collapsed. The summary is removed from the tab order and marked aria-disabled, and the whole component is dimmed. The attribute can be toggled at runtime.

<details-summary disabled>
    <details>
        <summary>Unavailable</summary>
        <div class="details-content">You cannot open or close this.</div>
    </details>
</details-summary>

The dimming opacity can be customized with the --details-summary-disabled-opacity CSS variable (defaults to 0.4).

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-disabled-opacity | 0.4 | Opacity of the component when disabled |

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>