Expandable Container

Expandable Container hides and shows information to create a focused experience for our users.

yarn add @workday/canvas-kit-labs-react
yarn add @workday/canvas-kit-labs-react


Image of an Expandable Container in its collapsed and expanded states.

  1. Chevron Icon: This is part of the header to indicate the opened or closed state of the container. This icon could be placed on the left or right side of the header. When the chevron is on the left of the Title, it shows Chevron Right for 'collapsed' and Chevron Down for 'expanded.' When the chevron is on the right of the Title, it shows Chevron Down for 'collapsed' and Chevron Up for 'expanded.'
  2. Avatar Indicator (Optional): This is used to display a user photo for containers that are user related. If there is no user photo available, it shows the default user icon.
  3. Title: The heading text for the information being shown in the content section.
  4. Content Section: This section is where users can find more information and details about the container's subject.

Usage Guidance

  • This component highlights the most important details of a section and reveals more when a user taps or clicks on the header part of the container.
  • Enabling users to hide and show information ensures the design remains focused and relevant to their expectations.
  • Scanning through the most critical information first makes processing more efficient without compromising the ability to access additional information.

When to Use

Use an Expandable Container when there is a lot of information to be shown on a page, but some details can initially be hidden from view.

When to Use Something Else

Be cautious of hiding critical information or burdening the user with an extra click if they are likely to read all the content. There is a chance that content hidden within the collapsed state will not be read or immediately noticed by users.


Start Icon

For a basic expandable container with a chevron icon before the title, placeExpandable.Icon before Expandable.Title as children of Expandable.Target and pass the iconPosition prop to Expandable.Icon with a value of start. Expandable.Icon will use a right chevron icon when collapsed and a down chevron icon when expanded.

End Icon

For an expandable container with a chevron icon after the title, place Expandable.Title before Expandable.Icon as children of Expandable.Target and pass the iconPosition prop to Expandable.Icon with a value of end. Expandable.Icon will use a down chevron icon when collapsed and an up chevron icon when expanded.

With Avatar

To include an avatar image, Expandable.Avatar should be placed between Expandable.Icon and Expandable.Title. An iconPosition prop with a value of either start or end should be passed to Expandable.Icon depending on whether the Expandable.Icon is placed before or after Expandable.Title.

Right to Left (RTL)

Expandable container has bidirectional support and should function as expected with RTL languages as long as the content direction is set in your Canvas theme.


The depth prop passed to Expandable allows you to adjust the visual elevation of a component using our depth tokens.

Title Wrap

Long titles will wrap to the next line and increase the height of the container.

Component API



Expandable wraps an Expandable.Target and an Expandable.Content. By default, it provides a DisclosureModel for its sub components. Alternatively, a model may be passed in using the hoisted model pattern.




Expandable.Target creates a heading and a button. The heading is a semantic heading to describe the associated content. The button provides users the ability to toggle the associated content.

As according to the W3 disclosure specification, the button has aria-expanded and aria-controls attributes set by default

This component should hold an Expandable.Icon, an optional Expandable.Avatar, and an Expandable.Title.


headingLevel is the only prop spread to the underlying heading. All other props are spread to the button.



Expandable.Title styles the target text that describes the content.




Expandable.Icon creates an icon to visually indicate the state of the content. It takes an iconPosition prop to determine which chevron icon to use.


iconPosition takes a value of either start or end. If no value is provided, it will default to start. Given a value of start it will use a chevron that points down when the container is expanded and right when the container is collapsed. Given a value of end, it will use a chevron that points up when the container is expanded and down when the container is collapsed.



Expandable.Avatar is an optional component that creates an Avatar to display a decorative image.




Expandable.Content holds the content that will be conditionally expanded and collapsed. It has an id to ensure the Expandable.Target properly set it to the aria-controls attribute.


Accessibility Guidelines

  • The state of a component being open or closed must be conveyed to assistive technologies.
  • A Button must be used as the control to toggle the display of any content.
  • If there are multiple toggle Buttons on the same page, provide additional information in their labels to make them uniquely distinguishable to a screen reader.
  • Do not change the toggle Button label to convey state. An exception to this would be a scenario where a visual hint text is decoupled from both the state and the label for a control so the hint text is not announced by assistive technologies.
  • Avoid keyboard traps when adding components to the accordion panel. For example, the user expands an accordion, but is unable to tab to the next focusable element.
  • Hidden content must be hidden correctly from keyboard, screen reader, and touch interaction.
  • Changing the label of something to indicate its state will not always be accounted for in live time for a screen reader user. For example, a play button should have a non-changing, persistent label and the state (pressed or unpressed) is conveyed visually as well as to assistive technology once the state is changed.

Content Guidelines

  • Titles should be short and concise, yet long enough to explain what the user would expect to see when the content is expanded.
  • If titles must be long, make sure it doesn't wrap more than two lines.

Can't Find What You Need?

Check out our FAQ section which may help you find the information you're looking for.

FAQ Section