Skip to content

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
basic-default-open.svelte
<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
starting-closed.svelte
<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
with-icon.svelte
<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
header-actions-extrabuttons.svelte
<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
controlled.svelte
<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

NameTypeDefaultDescription
titlerequiredstring—Header text.
defaultOpenbooleantrueInitial open state (uncontrolled mode).
openboolean—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.
childrenrequiredSnippet<[]>—Section content.
iconstring—Iconify icon shown before the title.
extraButtonsExtraButton[][]Small Button instances beside the chevron. showWhenCollapsed chooses visibility when the section is collapsed vs expanded.
contentPaddingbooleantrueApply default padding to the content area.
fullHeightbooleanfalseStretch to fill parent height when open.
classClassValue—Additional CSS classes on the root.
stylestring—Inline styles on the stable component root.
titleVariant"default" | "sidebar"'default'Default title or compact sidebar typography.
headerClassClassValue—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; use open + onToggle for external control.
  • The extraButtons prop 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 fullHeight inside 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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.