Details

A disclosure panel that animates open, alone or as an exclusive accordion.

zweiundeins <sb-details> details disclosure accordion collapse expand summary faq Since 2026-09-23 MIT licence 2.0 kB0 Open in playground Edit on GitHub

Playground

Burn 4.2 s at T+38, then coast to the transfer orbit.

A summary row that opens to reveal its content, with a height animation that always lands on the content's own height. On its own it is a disclosure; give a few of them the same group and they become an accordion where only one panel is open.

open is view state, not a value: the server may own it, it reports changes with its own sb-toggle event, and it never takes part in a pending or revert() flow.

Examples

A single panel

Click the row, or focus it and press Enter or Space.

A custom element declared with rocket(). It renders its own shadow DOM from Datastar signals, so the page can wire it with attributes only. open on the first render opens the panel without an animation.
<div style="display: grid; gap: 8px; inline-size: min(100%, 26rem)">
  <sb-details summary="What is a Rocket component?" icon="๐Ÿš€">
    A custom element declared with <code>rocket()</code>. It renders its own shadow DOM from
    Datastar signals, so the page can wire it with attributes only.
  </sb-details>
  <sb-details open summary="Already open">
    <code>open</code> on the first render opens the panel without an animation.
  </sb-details>
</div>

An accordion

Panels that share a group close each other. Every panel that closes emits its own sb-toggle, so the page (or the server) can keep the whole group's state. Render at most one of them open: as with <details name>, a panel that arrives open while another one in its group is open starts closed.

Two Raptor-class thrusters, 1.8 MN combined. Ablative ceramic over a titanium frame. Four, plus provisions for 90 days.

Last sb-toggle:

<div data-signals="{_last: 'โ€”'}" style="display: grid; gap: 8px; inline-size: min(100%, 26rem)">
  <sb-details group="specs" name="engine" summary="Engine" icon="๐Ÿ”ฅ"
    data-on:sb-toggle="$_last = evt.detail.name + ' โ†’ ' + evt.detail.open">
    Two Raptor-class thrusters, 1.8 MN combined.
  </sb-details>
  <sb-details group="specs" name="hull" summary="Hull" icon="๐Ÿ›ก๏ธ"
    data-on:sb-toggle="$_last = evt.detail.name + ' โ†’ ' + evt.detail.open">
    Ablative ceramic over a titanium frame.
  </sb-details>
  <sb-details group="specs" name="crew" summary="Crew" icon="๐Ÿ‘ฉโ€๐Ÿš€"
    data-on:sb-toggle="$_last = evt.detail.name + ' โ†’ ' + evt.detail.open">
    Four, plus provisions for 90 days.
  </sb-details>
  <p>Last <code>sb-toggle</code>: <b data-text="$_last"></b></p>
</div>

When the server owns the open state

The buttons below stand in for the server: they add or remove the open attribute, exactly like a re-render would. A changed attribute wins over whatever the user did: adding it opens the panel, removing it closes it. data-attr removes the attribute for false, and data-preserve-attr keeps a signal-driven attribute through a morph.

Server sends open Server removes open
Toggle the panel by hand, then press a button: the attribute wins. Press the same button twice and nothing happens: re-sent identical markup is not a change.
<div data-signals="{_open: false}" style="display: grid; gap: 10px; inline-size: min(100%, 26rem)">
  <div style="display: flex; gap: 8px; flex-wrap: wrap">
    <sb-button size="sm" data-on:click="$_open = true">Server sends open</sb-button>
    <sb-button size="sm" variant="outline" data-on:click="$_open = false">Server removes open</sb-button>
  </div>
  <sb-details name="brief" summary="Mission brief" data-attr:open="$_open" data-preserve-attr="open">
    Toggle the panel by hand, then press a button: the attribute wins. Press the same button
    twice and nothing happens: re-sent identical markup is not a change.
  </sb-details>
</div>

On a Starbase page the same thing is one sb-toggle handler and one command:

<sb-details name="brief" summary="Mission brief" {{ if .Brief }}open{{ end }}
  data-on:sb-toggle="@post('/cmd/panel', {payload: {tabid: $tabid, ...evt.detail}})">
  โ€ฆ
</sb-details>

The command writes the panel into tab_state, the next render brings the open attribute back, and nothing was ever shown before the server produced it.

View state, not a value

A value is what the user decides; view state is what they look at. sb-details only ever holds the second, and that changes the contract in three ways (Components with several values):

  • Its event is sb-toggle, not sb-change. { name, open }, on every open and close, including the panels an accordion closes for you.
  • There is no confirm and no revert(). Nothing here is "not confirmed yet": a panel the user opened is open, whatever the server thinks. A failed command simply leaves the next render's open attribute as it was, and that attribute wins.
  • The server can still own it. open behaves like every other server-driven attribute:
The server sends What happens
open on the first render Open on the first paint, with no opening animation
a changed open attribute It wins, whatever the user had done. No sb-toggle is emitted: the server already knows
the same markup again Nothing. A morph can never re-open a panel the user just closed
no open attribute any more Closed, whatever the user had done. This is how the server closes a panel
open="false" Open: any value is present, as in HTML. Leave the attribute out to close

Local toggling never writes the attribute back, which is what makes the table above consistent. A panel that app code moves (a sortable list, a portal, moveBefore) keeps its open state, like a native <details>, and an open attribute changed while it was detached still wins when it comes back.

One implementation note, since other components may want to copy this: sb-details watches the open attribute (a MutationObserver on the host) and reads it by presence itself, as HTML does, not through the decoded prop.

A native <details> in the shadow root

The panel is a real <details> and <summary>, inside the component's shadow root. That is the whole design:

  • Native semantics for free. The disclosure role and expanded state, Enter and Space on the summary, the browser's own find-in-page reaching closed content and opening the panel: none of it is re-implemented, so none of it can drift from what the platform does.
  • The shadow root keeps the server-owned attribute clean. A <details> reflects its state into its own open attribute, which is exactly why a <details> in a morphed page needs data-preserve-attr="open": the attribute is both the server's instruction and the browser's scratch space. Here the reflected attribute is inside the shadow root, where a morph never goes, while the host's open attribute is only ever read. The two never meet.
  • The animation is the browser's box. ::details-content is the box the browser already wraps the revealed content in, so it grows from block-size: 0 to auto (with interpolate-size: allow-keywords) and lands on the content's own height. Nothing is measured, and content-visibility flips discretely at the ends, which is what keeps closed content out of the layout, out of the tab order and still findable.

Where ::details-content or interpolate-size is not supported, the panel simply opens and closes at once; everything else is unchanged.

Only one thing is not native: group. <details name="โ€ฆ"> groups exclusively within a single tree scope, and each host has its own shadow root, so no two panels are ever in the same one. A small module-level registry does it instead, which is also what lets a closing sibling emit its own sb-toggle.

Props

summary is the heading (the summary slot replaces it), icon a decorative glyph before it, disabled blocks toggling (the server can still open or close it), group makes an accordion, and name is what sb-toggle reports.

host.open reads and writes the live state, and show() / hide() do the same; all three emit sb-toggle, because a page asking for a change is a change.

A slotted summary row ๐Ÿ› ๏ธ Any markup can go in the summary slot.
show() hide()
Locked by the server.
<div style="display: grid; gap: 8px; inline-size: min(100%, 26rem)">
  <sb-details data-ref:_panel>
    <b slot="summary">A slotted summary row ๐Ÿ› ๏ธ</b>
    Any markup can go in the <code>summary</code> slot.
  </sb-details>
  <div style="display: flex; gap: 8px">
    <sb-button size="sm" data-on:click="$_panel.show()">show()</sb-button>
    <sb-button size="sm" variant="outline" data-on:click="$_panel.hide()">hide()</sb-button>
  </div>
  <sb-details disabled summary="Disabled" icon="๐Ÿ”’">Locked by the server.</sb-details>
</div>

Styling

Parts: details (the <details> box), summary, icon, label, marker (the triangle, mirrored in right-to-left text) and content (the body inside the panel). The animated box itself is the browser's ::details-content, which no part can name; its speed is --sb-details-duration.

The open panel is sb-details::part(details):open. Not sb-details[open]: the host's open attribute is the server's word, not the live state.

It styles against the semantic tokens (--sb-surface-card, --sb-surface-hover, --sb-border, --sb-text-1, --sb-text-2, --sb-text-muted, --sb-brand-light, --sb-radius) and notches its corners by --sb-notch (at 0 the radius takes over, and the stepped marker becomes a plain triangle that turns smoothly). --sb-details-duration (220 ms) sets the animation, and prefers-reduced-motion: reduce turns it off, opening and closing at once.

No notches, and a long animation. Re-map the tokens rather than hard-coding colours, and it still works on every theme.
<div style="display: grid; gap: 8px; inline-size: min(100%, 26rem)">
  <sb-details open summary="Slow and smooth" style="--sb-notch: 0; --sb-details-duration: 600ms">
    No notches, and a long animation.
  </sb-details>
  <sb-details open summary="Tinted panel" style="--sb-surface-card: var(--sb-brand-subtle); --sb-border: var(--sb-brand)">
    Re-map the tokens rather than hard-coding colours, and it still works on every theme.
  </sb-details>
</div>

Accessibility

  • Summary: a real <summary>, so the disclosure role, Enter and Space and every assistive technology's "expand" come from the browser. aria-expanded is kept in sync with it for the engines that do not expose the native state.
  • Panel: role="region" named by the summary (aria-labelledby), which puts it in the landmark and rotor lists while it is open.
  • Closed content: the browser's own content-visibility: hidden on ::details-content keeps it out of the accessibility tree and out of the tab order, and find-in-page still reaches it and opens the panel.
  • Motion: prefers-reduced-motion: reduce removes the height transition and the marker's rotation; the panel still opens and closes.
  • Forced colours: the marker is drawn in CanvasText, and the focus ring is an outline, which forced colours keep.
  • Disabled: <summary> has no disabled state, so the component sets aria-disabled and tabindex="-1" (out of the tab order) and cancels the default action of the click, which is also what Enter and Space trigger.

Installation

Add Datastar with Rocket and the Starbase autoloader once per page, then use the tag: the autoloader imports each component the first time its tag appears, including tags a Datastar morph adds later. The Datastar here is v1.0.5 with Starbase's patches. The components also run on the official v1.0.4 and v1.0.5.

<script type="importmap">
  { "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" } }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/autoloader.js"></script>

<sb-details summary="Flight plan">Burn 4.2 s at T+38, then coast to the transfer orbit.</sb-details>

No flash of undefined elements: put class="sb-cloak" on <html> and add .sb-cloak :not(:defined) { visibility: hidden } to your CSS. The autoloader removes the class once the page's components are defined.

Load just this component, pinned to this version: all its modules in one minified file with its integrity hash, so the browser refuses it if a single byte changes.

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/details@944a4431231b/details.bundle.min.js" integrity="sha384-QnSJXz+5xBBCTd9n1ZrMLKKCGmftZxdFOMB07y6UMsSrMkvsI1CAEUTty+M1V/+K"></script>

<sb-details summary="Flight plan">Burn 4.2 s at T+38, then coast to the transfer orbit.</sb-details>

Or the minified module files (one file, which the browser requests as it finds their imports), each pinned in the import map:

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
      "https://starbase.zweiundeins.gmbh/c/details@944a4431231b/details.min.js": "sha384-QNIGwQE8i4sVe4fn5xl1WN1Pt+HfE1ELzKlB2vO9P8Ps3OZnX/RF9UsQjS+4j+HH"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/details@944a4431231b/details.min.js" integrity="sha384-QNIGwQE8i4sVe4fn5xl1WN1Pt+HfE1ELzKlB2vO9P8Ps3OZnX/RF9UsQjS+4j+HH"></script>

<sb-details summary="Flight plan">Burn 4.2 s at T+38, then coast to the transfer orbit.</sb-details>

In production, pin today's whole catalog: its autoloader and an import map with integrity hashes, so the browser refuses any file that changed. This map covers Datastar and this component; importmap.json has the hashes of every component, to merge into yours.

<script type="importmap">
  {
    "imports": { "datastar": "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js" },
    "integrity": {
      "https://starbase.zweiundeins.gmbh/c/datastar@5f98646d7d3d/datastar-rocket.js": "sha384-AfXVdZ/qxhMEHK4Nz/pJT6jl9xm3HGMBLBtC9yRuU5A7AQtXHYC0x6ap034vDqBV",
      "https://starbase.zweiundeins.gmbh/c/details@944a4431231b/details.bundle.min.js": "sha384-QnSJXz+5xBBCTd9n1ZrMLKKCGmftZxdFOMB07y6UMsSrMkvsI1CAEUTty+M1V/+K"
    }
  }
</script>
<script type="module" src="https://starbase.zweiundeins.gmbh/c/@81f24b268adb/autoloader.js" integrity="sha384-bWIhsIq9SpNUiIZyG/lv190MgHA05m8BVYA3LyIoE/pgOF3NUt0437e++4Ht1NcS"></script>

<sb-details summary="Flight plan">Burn 4.2 s at T+38, then coast to the transfer orbit.</sb-details>

Components import only datastar and their own files, so copying is enough: save each component's one file (and a file it loads on first use, keeping its folder), and point the import map at your own copy of datastar-rocket.js (the /js/ paths stand for yours).

  • <sb-details>
    • details.bundle.min.js one file 2.0 kB brotli
<script type="importmap">
  { "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/details/details.bundle.min.js"></script>

<sb-details summary="Flight plan">Burn 4.2 s at T+38, then coast to the transfer orbit.</sb-details>

Or copy the module files, keeping each component's folder, and load each component's module:

  • <sb-details>
<script type="importmap">
  { "imports": { "datastar": "/js/datastar-rocket.js" } }
</script>
<script type="module" src="/js/details/details.min.js"></script>

<sb-details summary="Flight plan">Burn 4.2 s at T+38, then coast to the transfer orbit.</sb-details>

In Go, render it with its typed templ wrapper: one field per prop, generated from the component's manifest (the module's README has the type rules). Add the module:

go get github.com/zweiundeins/starbase/templ@latest

Then load it, pinned with integrity hashes to the versions the module was generated with, and use it:

// In <head>: the components you list, pinned,
@sb.Imports(sb.ImportsProps{Components: []sb.Tag{sb.TagDetails}})
// or the autoloader, which also loads tags a morph adds later: @sb.Imports(sb.ImportsProps{})
// or, around the content of <body>, the components it renders: @sb.Tracked(sb.ImportsProps{}) { โ€ฆ }

@sb.Details(sb.DetailsProps{Summary: "Flight plan"}) {
	Burn 4.2 s at T+38, then coast to the transfer orbit.
}

Size

A page loads this component as one file, its bundle, compressed the way it is served (gzip -9, brotli -11): brotli is what it downloads. Datastar and Rocket are shared by every component and not counted.

FileOriginalgzipbrotli
details.bundle.min.js 5.2 kB2.2 kB2.0 kB
As module files: one request, 1.9 kB minified with brotli

For a page that loads the module files as they are, requesting each one as it finds its import, or bundles them itself. Each file compressed on its own; the minified one is what the page downloads, and the readable source is always there too.

FileOriginalgzipbrotliminified
details.js 12.7 kB5.0 kB4.3 kB1.9 kB

API reference

Props

AttributeTypeDefaultDescription
summarystring"Details"The heading on the summary row. The server can morph it; the summary slot overrides it.
openbooleanfalseOpen when present. View state, not a value: the server adding or removing the attribute wins, identical markup keeps the local state. Local toggling never reflects it.
iconstring""Short text or emoji before the summary (decorative).
disabledbooleanfalseBlock toggling. The server can still open or close it.
groupstring""Accordion group: opening one sb-details with this group name closes the others, and each of them emits its own sb-toggle.
namestring""Name reported in sb-toggle (e.g. the field of a command).

Slots

NameDescription
defaultThe content the panel reveals.
summaryRich content for the summary row; replaces the summary prop.

Events

NameDescription
sb-toggleThe panel opened or closed. detail: { name, open }. View state: never pending, and not emitted for a change the server itself made.