Collapsible

Imports

The package root exports the component (named) and its props type. The stylesheet is a separate subpath export — import it once at your app root, or nothing animates.

Props

Three props are required — children, id, open. Everything else has a default or passes through.

id

id lands on the outer container and is the component's half of the accessibility contract: the trigger must carry aria-controls equal to this id, plus aria-expanded mirroring the state. The id is how assistive technology connects the button to the panel it controls.

In development builds, the first time an instance opens, the component checks the document for an element with aria-controls matching its id — and warns once in the console if none exists. Production builds skip the check entirely.

open

The component is fully controlled — open is the single source of truth, and toggling lives in your code: useState, a reducer, a store selector, anything that yields a boolean.

One internal subtlety worth knowing: when open flips to true, the grid transition starts immediately, but the [open] attribute and any open:/closed: conditional classes flip one animation frame later (via requestAnimationFrame) so the browser registers their pre-transition styles first — that deferral is what makes transitions keyed on them fire reliably. Closing applies immediately. Controlled state covers this end to end.

direction

'y' (the default) animates grid-template-rows — a height collapse. 'x' animates grid-template-columns — a width collapse. Horizontal collapse has two layout requirements: the parent typically needs display: flex so the container can shrink to zero width, and the content usually wants white-space: nowrap or a fixed width so text doesn't reflow mid-animation. The horizontal collapse guide works through both.

transitionDuration

Any CSS time value — '300ms', '0.5s'. The stylesheet defaults to 500ms; this prop is inlined as a style on the outer container, so it overrides both the stylesheet default and any transitionDuration key in the style prop. For easing curves and motion preferences, see custom transitions.

initialOpen

A panel that mounts with open={true} would otherwise animate from collapsed on first paint. initialOpen suppresses that: the component forces transitionDuration: '0s' for the first frame, then restores the configured duration. The panel appears open instantly, and every toggle after that animates normally.

initialOpen only skips the animation — it does not open the panel. Pair it with state that starts true.

hideMode

'remove' (the default) gives collapsed content display: none — it leaves the document flow and the accessibility tree. 'hide' keeps display: grid but applies visibility: hidden, so the content stays in the DOM: form input state, iframes, and measurements all survive a collapse. In hide mode the inner wrapper also carries aria-hidden mirroring the state, so screen readers skip the invisible content. The trade-offs are covered in hide modes.

className

Applied to the inner content wrapper, not the outer container. Two prefixes make classes conditional: open:foo applies foo only while expanded, closed:bar applies bar only while collapsed; unprefixed classes always apply. The conditional classes flip on a RAF-deferred copy of open, so paired transition-* utilities fire reliably and run in sync with the collapse animation — fade content as the panel grows, for instance. Full treatment in conditional classes.

style

Merged onto the outer container — the element that owns the grid transition. A transitionDuration key here works as an override of the stylesheet default, but loses to the transitionDuration prop when both are set, and to the forced 0s during an initialOpen first frame.

Everything else

All remaining div props — data-* attributes, role, event handlers — spread onto the outer container. id is the one exception: it is omitted from the passthrough type and always set from the id prop, because the accessibility contract depends on it.