CollapsibleSection
Expandable/collapsible content section with a clickable header, optional icon, and extra action buttons. Supports both controlled and uncontrolled open state.
import { CollapsibleSection } from "phoundry-ui";Basic (Default Open)
Loading interactive example…
View source
<script lang="ts"> import { CollapsibleSection } from "phoundry-ui";</script>
<CollapsibleSection title="Details"> <p class="text-xs text-txt-secondary">This content is visible by default.</p></CollapsibleSection>Starting Closed
Loading interactive example…
View source
<script lang="ts"> import { CollapsibleSection } from "phoundry-ui";</script>
<CollapsibleSection title="Advanced Settings" defaultOpen={false}> <p class="text-xs text-txt-secondary">Hidden until expanded.</p></CollapsibleSection>With Icon
Loading interactive example…
View source
<script lang="ts"> import { CollapsibleSection } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui";</script>
<CollapsibleSection title="Configuration" icon={PhiIcons.edit}> <p class="text-xs text-txt-secondary"> Section with a leading icon in the header. </p></CollapsibleSection>Header actions (extraButtons)
Loading interactive example…
View source
<script lang="ts"> import { CollapsibleSection } from "phoundry-ui"; import { PhiIcons } from "phoundry-ui";</script>
<p class="mb-2 text-xs text-txt-secondary"> <code>stopPropagation</code> on the extra button wrapper keeps header toggles separate from actions.</p><CollapsibleSection title="Tasks" icon={PhiIcons.edit} defaultOpen={false} extraButtons={[ { showWhenCollapsed: true, button: { variant: "ghost", size: "sm", icon: PhiIcons.add, title: "Quick add", onclick: () => {}, }, }, { showWhenCollapsed: false, button: { variant: "ghost", size: "sm", icon: PhiIcons.refresh, title: "Refresh list", onclick: () => {}, }, }, ]}> <p class="text-xs text-txt-secondary"> Collapsed: only the “add” icon shows. Expanded: refresh appears. </p></CollapsibleSection>Controlled
Loading interactive example…
View source
<script lang="ts"> import { CollapsibleSection } from "phoundry-ui";
let controlledOpen = $state(true);</script>
<div class="space-y-2"> <button class="rounded bg-surface-raised px-2 py-1 text-xs text-txt-secondary transition-colors hover:bg-surface-overlay" onclick={() => { controlledOpen = !controlledOpen; }} > {controlledOpen ? "Collapse" : "Expand"} </button> <CollapsibleSection title="Controlled" open={controlledOpen} onToggle={() => { controlledOpen = !controlledOpen; }} > <p class="text-xs text-txt-secondary">Externally controlled open state.</p> </CollapsibleSection></div>API
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
titlerequired | string | — | Header text. |
defaultOpen | boolean | true | Initial open state (uncontrolled mode). |
open | boolean | — | Controlled open state - overrides internal state when provided. |
onToggle | () => void | — | Called on toggle. When provided, component becomes fully controlled. |
onOpenChange | (open: boolean) => void | — | Called with the new open state after toggle. |
childrenrequired | Snippet<[]> | — | Section content. |
icon | string | — | Iconify icon shown before the title. |
extraButtons | ExtraButton[] | [] | Small Button instances beside the chevron. showWhenCollapsed chooses visibility when the section is collapsed vs expanded. |
contentPadding | boolean | true | Apply default padding to the content area. |
fullHeight | boolean | false | Stretch to fill parent height when open. |
class | ClassValue | — | Additional CSS classes on the root. |
style | string | — | Inline styles on the stable component root. |
titleVariant | "default" | "sidebar" | 'default' | Default title or compact sidebar typography. |
headerClass | ClassValue | — | Additive classes on the header. |
Usage tips
- The header row uses
role="button"with keyboard activation - ensure titles stay concise for screen readers. - Use uncontrolled mode (just
defaultOpen) for simple cases; useopen+onTogglefor external control. - The
extraButtonsprop lets you add action buttons (e.g. “Add”, “Edit”) to the header row alongside the toggle. - Set
contentPadding={false}when embedding full-bleed content like tables or lists. - Use
fullHeightinside flex layouts where the section should stretch to fill remaining space.
Styling
.ph-collapse is the stable root hook. Consumer class values are additive, and style applies to that root. Styling uses vanilla CSS with semantic state attributes. The header remains the headerClass target, exposes aria-expanded, and uses data-title-variant for default/sidebar typography. The root exposes data-full-height; content exposes data-padded. Existing controlled/uncontrolled callbacks, extra buttons, padding, and full-height behavior are preserved. Header actions appear on hover or keyboard focus within the header. Reduced motion skips the content transition. Internal part selectors and --_ph-* properties remain implementation details.