Collapsible

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

styleKeys: 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">Content.</BasicCollapsible>

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

<div class="swan-collapsible">
  <div class="swan-collapsible-summary">
    <button
      aria-expanded="false"
      class="swan-collapsible-summary-button"
      aria-controls="content-1"
    >
      Summary
    </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"
    >
      Summary
    </button>
  </div>
  <div class="swan-collapsible-content" id="content-1">Content.</div>
</div>

Collapsible

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

ReactVanilla

<Collapsible>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<Collapsible>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</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"
    >
      Summary
    </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"
    >
      Summary
    </button>
  </div>
  <div class="swan-collapsible-content" id="content-1">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>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>
      <CollapsibleSummaryTextOpen>
        Summary text when open
      </CollapsibleSummaryTextOpen>
      <CollapsibleSummaryTextClosed>
        Summary text when closed
      </CollapsibleSummaryTextClosed>
    </CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content.</CollapsibleContent>
</Collapsible>

<Collapsible>
  <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">
    <button
      aria-expanded="false"
      class="swan-collapsible-summary-button"
      aria-controls="content-1"
    >
      <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>
  </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"
    >
      <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>
  </div>
  <div class="swan-collapsible-content" id="content-1">Content.</div>
</div>

Default expanded

Use defaultExpanded to present the Collapsible as expanded by default.

ReactVanilla

<Collapsible defaultExpanded>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content</CollapsibleContent>
</Collapsible>

<Collapsible defaultExpanded>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content</CollapsibleContent>
</Collapsible>

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

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

Disabled

Use disabled to prevent the Collapsible from expanding.

ReactVanilla

<Collapsible disabled>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content</CollapsibleContent>
</Collapsible>

<Collapsible disabled>
  <CollapsibleSummary>
    <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
  </CollapsibleSummary>
  <CollapsibleContent>Content</CollapsibleContent>
</Collapsible>

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

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

Full Bleed

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

ReactVanilla

<Collapsible fullBleed>
  <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>
  <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">
    <button
      aria-expanded="false"
      class="swan-collapsible-summary-button"
      aria-controls="content-1"
    >
      Summary
    </button>
  </div>
  <div class="swan-collapsible-content" id="content-1">
    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">
    <button
      aria-expanded="false"
      class="swan-collapsible-summary-button"
      aria-controls="content-1"
    >
      Summary
    </button>
  </div>
  <div class="swan-collapsible-content" id="content-1">
    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
      expanded={expanded}
      onRequestExpandedChange={exp => setExpanded(exp)}
    >
      <CollapsibleSummary>
        <CollapsibleSummaryButton>Summary</CollapsibleSummaryButton>
      </CollapsibleSummary>
      <CollapsibleContent>Content</CollapsibleContent>
    </Collapsible>
  )
}

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

Accessibility

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.

Props

BasicCollapsible

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.