Collapsible

A Collapsible is a section that can be toggled open and closed. It is typically grouped with other Collapsible into an Accordion.

styleKey: accordion

UsageGuidelinesAPI

Use Collapsible...

To present a large amount of content in a compact form.
To prevent information overload by allowing users to expand only the section they are interested in.
Use as part of an Accordion for showing multiple Collapsibles

Don't use Collapsible...

To display critical information. Use a Modal Dialog instead.
To present a small amount of content where the benefit of collapsing/expanding is minimal. Use a Card instead.

Basic Collapsible

Use the BasicCollapsible Convenience Component for the most common use-cases.

ReactVanilla

<BasicCollapsible heading="Summary" headingLevel="h2">
  Content.
</BasicCollapsible>

<BasicCollapsible heading="Summary" headingLevel="h2">
  Content.
</BasicCollapsible>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="content-1"
      >
        Summary
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="content-1">Content.</div>
</div>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="content-1"
      >
        Summary
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="content-1">Content.</div>
</div>

Collapsible

Use Collapsible with different properties to build your own when the Convenience Component doesn’t match your needs.

ReactVanilla

<Collapsible headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<Collapsible headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-wtt1fjn3y-203"
      >
        Summary
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="auto-id-wtt1fjn3y-203">
    Content.
  </div>
</div>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-wtt1fjn3y-203"
      >
        Summary
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="auto-id-wtt1fjn3y-203">
    Content.
  </div>
</div>

Text Closed / Text Open summary

Use CollapsibleSummaryTextClosed and CollapsibleSummaryTextOpen inside CollapsibleSummary to enable a different summary text depending on whether the Collapsible is collapsed or expanded.

ReactVanilla

<Collapsible headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>
      <CollapsibleSummaryTextOpen>
        Summary text when open
      </CollapsibleSummaryTextOpen>
      <CollapsibleSummaryTextClosed>
        Summary text when closed
      </CollapsibleSummaryTextClosed>
    </CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<Collapsible headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>
      <CollapsibleSummaryTextOpen>
        Summary text when open
      </CollapsibleSummaryTextOpen>
      <CollapsibleSummaryTextClosed>
        Summary text when closed
      </CollapsibleSummaryTextClosed>
    </CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-iwknk1110-170"
      >
        <span class="swan-collapsible-summary-text-open"
          >Summary text when open</span
        ><span class="swan-collapsible-summary-text-closed"
          >Summary text when closed</span
        >
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="auto-id-iwknk1110-170">
    Content.
  </div>
</div>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-iwknk1110-170"
      >
        <span class="swan-collapsible-summary-text-open"
          >Summary text when open</span
        ><span class="swan-collapsible-summary-text-closed"
          >Summary text when closed</span
        >
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="auto-id-iwknk1110-170">
    Content.
  </div>
</div>

Default expanded

Use defaultExpanded to present the Collapsible as expanded by default.

ReactVanilla

<Collapsible defaultExpanded headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content</CollapsibleContent>
</Collapsible>

<Collapsible defaultExpanded headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content</CollapsibleContent>
</Collapsible>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="true"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-iwknk1110-187"
      >
        Summary
      </button>
    </h2>
  </div>
  <div
    class="swan-collapsible-content swan-collapsible-content-open"
    id="auto-id-iwknk1110-187"
  >
    Content
  </div>
</div>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="true"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-iwknk1110-187"
      >
        Summary
      </button>
    </h2>
  </div>
  <div
    class="swan-collapsible-content swan-collapsible-content-open"
    id="auto-id-iwknk1110-187"
  >
    Content
  </div>
</div>

Disabled

Use disabled to prevent the Collapsible from expanding.

ReactVanilla

<Collapsible disabled headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content</CollapsibleContent>
</Collapsible>

<Collapsible disabled headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content</CollapsibleContent>
</Collapsible>

<div aria-disabled="true" class="swan-collapsible swan-collapsible-disabled">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-iwknk1110-202"
      >
        Summary
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="auto-id-iwknk1110-202">Content</div>
</div>

<div aria-disabled="true" class="swan-collapsible swan-collapsible-disabled">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-iwknk1110-202"
      >
        Summary
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="auto-id-iwknk1110-202">Content</div>
</div>

Full Bleed

fullBleed is deprecated in SWAN v3.37.0

Collapsible displays the content full bleed by default.

Use fullBleed to remove the right padding of the content within the Collapsible.

ReactVanilla

<Collapsible fullBleed headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>
    Content using full bleed. This collapsible's content will go all the way out
    to the right edge. This collapsible's content will go all the way out to the
    right edge. This collapsible's content will go all the way out to the right
    edge. This collapsible's content will go all the way out to the right edge.
  </CollapsibleContent>
</Collapsible>

<Collapsible fullBleed headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>
    Content using full bleed. This collapsible's content will go all the way out
    to the right edge. This collapsible's content will go all the way out to the
    right edge. This collapsible's content will go all the way out to the right
    edge. This collapsible's content will go all the way out to the right edge.
  </CollapsibleContent>
</Collapsible>

<div class="swan-collapsible swan-collapsible-full-bleed">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-iwknk1110-215"
      >
        Summary
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="auto-id-iwknk1110-215">
    Content using full bleed. This collapsible's content will go all the way out
    to the right edge. This collapsible's content will go all the way out to the
    right edge. This collapsible's content will go all the way out to the right
    edge. This collapsible's content will go all the way out to the right edge.
  </div>
</div>

<div class="swan-collapsible swan-collapsible-full-bleed">
  <div class="swan-collapsible-summary">
    <h2>
      <button
        aria-expanded="false"
        class="swan-collapsible-summary-button"
        aria-controls="auto-id-iwknk1110-215"
      >
        Summary
      </button>
    </h2>
  </div>
  <div class="swan-collapsible-content" id="auto-id-iwknk1110-215">
    Content using full bleed. This collapsible's content will go all the way out
    to the right edge. This collapsible's content will go all the way out to the
    right edge. This collapsible's content will go all the way out to the right
    edge. This collapsible's content will go all the way out to the right edge.
  </div>
</div>

Managing state

Controlling the state of a Collapsible is only necessary if there's a need to read or write its state from another component. This requirement is rather uncommon.

In the React API, use expanded to indicating whether the Collapsible should be expanded or not.

Use the onRequestExpandedChange prop on the Collapsible to be notified when it wants to expand or collapse. This handler is invoked with the following argument:

expanded: to indicate whether the Collapsible seeks to be expanded or not.

() => {
  const [expanded, setExpanded] = React.useState(true)
  return (
    <Collapsible
      headingLevel="h2"
      expanded={expanded}
      onRequestExpandedChange={exp => setExpanded(exp)}
    >
      <CollapsibleSummary>
        <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
      </CollapsibleSummary>
      <CollapsibleContent>Content</CollapsibleContent>
    </Collapsible>
  )
}

() => {
  const [expanded, setExpanded] = React.useState(true)
  return (
    <Collapsible
      headingLevel="h2"
      expanded={expanded}
      onRequestExpandedChange={exp => setExpanded(exp)}
    >
      <CollapsibleSummary>
        <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
      </CollapsibleSummary>
      <CollapsibleContent>Content</CollapsibleContent>
    </Collapsible>
  )
}

Accessibility

Collapsible requires some props set for accessibility compliance:

Both BasicCollapsible and Collapsible are required to set the headingLevel prop to specify the heading tag (h1-h6) used to wrap the summary.
- Note this can be set to null when using BasicCollapsible or Collapsible in a nav sidebar where you shouldn't be using HTML headings.

In the Vanilla API, for each swan-collapsible-summary-button, add the following attributes:

aria-expanded: set this attribute to true or false to indicate whether the accordion is expanded or collapsed.
aria-controls: assign to this attribute the same ID value as the swan-collapsible-content section it controls.

In the React API, those attributes are handled for you.

Content

Use concise language for each summary to clearly indicate what is in its content, upon expanding the section.

Heading flexibility

Collapsible is flexible enough to support custom heading content and arrangements.

ReactVanilla

<Collapsible>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>
      Title
      <Typography fontSkin="body-standard">Secondary text</Typography>
    </CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<Collapsible>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>
      Title
      <Typography fontSkin="body-standard">Secondary text</Typography>
    </CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <button
      aria-expanded="false"
      class="swan-collapsible-summary-button"
      aria-controls="content-1"
    >
      Title
      <div class="swan-font-skin-body-standard">Secondary text</div>
    </button>
  </div>
  <div class="swan-collapsible-content" id="content-1">Content.</div>
</div>

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <button
      aria-expanded="false"
      class="swan-collapsible-summary-button"
      aria-controls="content-1"
    >
      Title
      <div class="swan-font-skin-body-standard">Secondary text</div>
    </button>
  </div>
  <div class="swan-collapsible-content" id="content-1">Content.</div>
</div>

Icons in Collapsible

An Icon can be placed inside CollapsibleSummaryButton. The order of the icon and label will match their DOM order.

<Collapsible headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>
      <FlexBox gap="between-icon-and-text" alignItems="center">
        <Icon iconType="image" />
        Summary
      </FlexBox>
    </CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<Collapsible headingLevel="h2">
  <CollapsibleSummary>
    <CollapsibleSummaryButton>
      <FlexBox gap="between-icon-and-text" alignItems="center">
        <Icon iconType="image" />
        Summary
      </FlexBox>
    </CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

Props

BasicCollapsible

See core props for additional props that can be applied to this component.

prop	type	required	default	deprecation notes
`disabled` Whether or not the collapsible can be expanded or collapsed	`booleannull`	false	false
⚠️ Deprecated `fullBleed` Used to unset the left and right padding of the Collapsible @deprecated This prop is deprecated without a replacement as full bleed is now the default behaviour.	`booleannull`	false	false	This prop is deprecated without a replacement as full bleed is now the default behaviour.
`onRequestExpandedChange` The event fired when the collapsible's expanded state changes	`((expanded: boolean) => void)null`	false	null
`expanded` Whether or not the collapsible is open, this makes the component controlled	`booleannull`	false	null
`defaultExpanded` The default expanded state of the Collapsible - used for uncontrolled components	`booleannull`	false	false
`collapsibleId` Used when a collapsible is used inside of an Accordion for tracking the open state of each panel	`stringnull`	false	null
`headingLevel` Specifies the heading tag (h1–h6) used to wrap the summary button for accessible markup	`"h1""h2""h3""h4""h5""h6"null`	false	null
`heading` Used to render the contents of the generated CollapsibleSummaryButton	`stringReactElement<any, stringJSXElementConstructor<any>>null`	false	null

Collapsible

See core props for additional props that can be applied to this component.

prop	type	required	default	deprecation notes
`expanded` Whether or not the collapsible is open, this makes the component controlled	`booleannull`	false	null
`onRequestExpandedChange` The event fired when the collapsible's expanded state changes	`((expanded: boolean) => void)null`	false	null
⚠️ Deprecated `fullBleed` Used to unset the left and right padding of the Collapsible @deprecated This prop is deprecated without a replacement as full bleed is now the default behaviour.	`booleannull`	false	false	This prop is deprecated without a replacement as full bleed is now the default behaviour.
`defaultExpanded` The default expanded state of the Collapsible - used for uncontrolled components	`booleannull`	false	false
`collapsibleId` Used when a collapsible is used inside of an Accordion for tracking the open state of each panel	`stringnull`	false	null
`disabled` Whether or not the collapsible can be expanded or collapsed	`booleannull`	false	false
`headingLevel` Specifies the heading tag (h1–h6) used to wrap the summary button for accessible markup	`"h1""h2""h3""h4""h5""h6"null`	false	null

Collapsible

Use Collapsible...

Don't use Collapsible...

Basic Collapsible

Collapsible

Text Closed / Text Open summary

Default expanded

Disabled

Full Bleed

Managing state

Accessibility

Content

Heading flexibility

Icons in Collapsible

Props

Related