Expandable Container

Anatomy

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.

Design Annotations Needed

• Specify the heading level for the Expandable Container title

Examples

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.

import {Expandable} from '@workday/canvas-kit-react/expandable';

export default () => (
  <Expandable>
    <Expandable.Target headingLevel="h4">
      <Expandable.Icon iconPosition="start" />
      <Expandable.Title>Title</Expandable.Title>
    </Expandable.Target>

    <Expandable.Content>Content</Expandable.Content>
  </Expandable>
);

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.

import {Expandable} from '@workday/canvas-kit-react/expandable';

export default () => (
  <Expandable>
    <Expandable.Target headingLevel="h4">
      <Expandable.Title>
        TitleTitleTitleTitleTitle TitleTitleTitleTitle TitleTitleTitle Title
      </Expandable.Title>
      <Expandable.Icon iconPosition="end" />
    </Expandable.Target>

    <Expandable.Content>Content</Expandable.Content>
  </Expandable>
);

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.

import {Expandable} from '@workday/canvas-kit-react/expandable';
// @ts-ignore: Cannot find module error
import testAvatar from './test-avatar.png';

export default () => (
  <div>
    <Expandable>
      <Expandable.Target headingLevel="h4">
        <Expandable.Icon iconPosition="start" />
        <Expandable.Avatar name="Avatar" url={testAvatar} />
        <Expandable.Title>Title</Expandable.Title>
      </Expandable.Target>

      <Expandable.Content>Content</Expandable.Content>
    </Expandable>
    <Expandable>
      <Expandable.Target headingLevel="h4">
        <Expandable.Avatar name="Avatar" url={testAvatar} />
        <Expandable.Title>Title</Expandable.Title>
        <Expandable.Icon iconPosition="end" />
      </Expandable.Target>

      <Expandable.Content>Content</Expandable.Content>
    </Expandable>
  </div>
);

Accessibility Note: In this situation, the Avatar is decorative and should not be announced to screen readers. The <Expandable.Avatar> component has isDecorative set to true by default to hide it from screen readers, as avatars in expandable headers are typically decorative when paired with adjacent text.

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.

import {Expandable} from '@workday/canvas-kit-react/expandable';
import {CanvasProvider} from '@workday/canvas-kit-react/common';

export default () => {
  return (
    <CanvasProvider dir="rtl">
      <Expandable>
        <Expandable.Target headingLevel="h4">
          <Expandable.Icon iconPosition="start" />
          <Expandable.Avatar name="Avatar" />
          <Expandable.Title>Title</Expandable.Title>
        </Expandable.Target>

        <Expandable.Content>Content</Expandable.Content>
      </Expandable>
      <Expandable>
        <Expandable.Target headingLevel="h4">
          <Expandable.Avatar name="Avatar" />
          <Expandable.Title>Title</Expandable.Title>
          <Expandable.Icon iconPosition="end" />
        </Expandable.Target>

        <Expandable.Content>Content</Expandable.Content>
      </Expandable>
    </CanvasProvider>
  );
};

Depth

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

import {Expandable} from '@workday/canvas-kit-react/expandable';

export default () => {
  return (
    <Expandable borderRadius="l" depth={3} margin="xxxs" padding="xs">
      <Expandable.Target headingLevel="h4">
        <Expandable.Title>Additional Information</Expandable.Title>
        <Expandable.Icon iconPosition="end" />
      </Expandable.Target>

      <Expandable.Content>This Expandable Container has a depth of 3.</Expandable.Content>
    </Expandable>
  );
};

Title Wrap

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

import {Expandable} from '@workday/canvas-kit-react/expandable';
// @ts-ignore: Cannot find module error
import testAvatar from './test-avatar.png';

export default () => (
  <Expandable>
    <Expandable.Target headingLevel="h4">
      <Expandable.Icon iconPosition="start" />
      <Expandable.Avatar name="Avatar" url={testAvatar} />
      <Expandable.Title>
        Our house special supreme pizza includes pepperoni, sausage, bell peppers, mushrooms,
        onions, and oregano.
      </Expandable.Title>
    </Expandable.Target>

    <Expandable.Content>Content</Expandable.Content>
  </Expandable>
);

You can also have direct access to the model if

Hoisted Model

If you need direct access to the model, you can hoist it with the useExpandableModel hook. In the example below, we’re hoisting the models to expand and collapse all three containers at once.

import React from 'react';

import {Expandable, useExpandableModel} from '@workday/canvas-kit-react/expandable';
import {Flex} from '@workday/canvas-kit-react/layout';
import {SecondaryButton} from '@workday/canvas-kit-react/button';
import {useUniqueId} from '@workday/canvas-kit-react/common';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const listStyles = createStyles({
  flexDirection: 'column',
  gap: system.space.x2,
  padding: system.space.zero,
  marginX: system.space.x4,
  marginY: system.space.zero,
});

export default () => {
  const modelOne = useExpandableModel();
  const modelTwo = useExpandableModel();
  const modelThree = useExpandableModel();

  const idOne = useUniqueId();
  const idTwo = useUniqueId();
  const idThree = useUniqueId();

  const handleExpandAll = () => {
    modelOne.events.show();
    modelTwo.events.show();
    modelThree.events.show();
  };

  const handleCollapseAll = () => {
    modelOne.events.hide();
    modelTwo.events.hide();
    modelThree.events.hide();
  };

  return (
    <Flex gap={system.space.x6} flexDirection="column">
      <Flex gap={system.space.x4}>
        <SecondaryButton onClick={handleExpandAll}>Expand All</SecondaryButton>
        <SecondaryButton onClick={handleCollapseAll}>Collapse All</SecondaryButton>
      </Flex>
      <Flex flexDirection="column">
        <Expandable model={modelOne}>
          <Expandable.Target headingLevel="h4">
            <Expandable.Title id={idOne}>Usage Guidance</Expandable.Title>
            <Expandable.Icon iconPosition="end" />
          </Expandable.Target>

          <Expandable.Content as="section" aria-labelledby={idOne}>
            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.
          </Expandable.Content>
        </Expandable>
        <Expandable model={modelTwo}>
          <Expandable.Target headingLevel="h4">
            <Expandable.Title id={idTwo}>Accessibility Guidelines</Expandable.Title>
            <Expandable.Icon iconPosition="end" />
          </Expandable.Target>

          <Expandable.Content as="section" aria-labelledby={idTwo}>
            <Flex as="ul" cs={listStyles}>
              <li>
                The state of a component being open or closed must be conveyed to assistive
                technologies.
              </li>
              <li>A Button must be used as the control to toggle the display of any content.</li>
              <li>
                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.
              </li>
              <li>
                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.
              </li>
              <li>
                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.
              </li>
              <li>
                Hidden content must be hidden correctly from keyboard, screen reader, and touch
                interaction.
              </li>
              <li>
                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.
              </li>
            </Flex>
          </Expandable.Content>
        </Expandable>
        <Expandable model={modelThree}>
          <Expandable.Target headingLevel="h4">
            <Expandable.Title id={idThree}>Content Guidelines</Expandable.Title>
            <Expandable.Icon iconPosition="end" />
          </Expandable.Target>
          <Expandable.Content as="section" aria-labelledby={idThree}>
            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.
          </Expandable.Content>
        </Expandable>
      </Flex>
    </Flex>
  );
};

Accessibility Note: When using multiple Expandable Containers on a page, use the as prop to render the <Expandable.Content> sub-component as an HTML <section> element. Then, use aria-labelledby to reference the unique id of the <Expandable.Title> element. This practice can be useful to screen reader users when multiple Expandable Containers are opened at one time for uniquely describing the boundaries of the expandable content.

Accessibility

Our Expandable component renders a semantic HTML <button> element to the DOM, with an optional parent heading element as defined by the headingLevel prop. The aria-expanded property is included on the button to indicate the state of the content to screen readers.

Accordion Pattern | APG | WAI | W3C

• Use the headingLevel prop to assign an appropriate heading level based on the context of the page content.
• When using Expandable Container for navigation elements, then we don’t recommend using the headingLevel prop. This will render only expandable buttons to the DOM, reserving headings for organizing content in the main body of the page.
• The as prop may also be used on <Expandable.Content> to render an HTML <ul> element for displaying a list of items. For example, check out Side Panel with Navigation.

Navigation

• Tab key: Moves focus to the next expandable button or focusable element
• Shift + Tab: Moves focus to the previous focusable element
• Enter or Space: Toggles the expanded/collapsed state

Screen Reader Experience

• The expandable button will be announced with its title text followed by the button role
• The current state will be announced as either “collapsed” or “expanded” (For example: “Usage Guidance, button, collapsed” or “Usage Guidance, button, expanded”)
• State Changes: When activating the button to expand content, screen readers will announce the new “expanded” state and vice versa when collapsing content.
• Content Regions: Screen reader users can use landmark navigation to jump between sections and each section will be announced with its associated title (For example: “Usage Guidance, landmark region”)
• Heading Structure: Using heading levels with expandable buttons allows screen reader users to navigate by headings, making the document structure and hierarchy easier to understand.

Component API

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

How Expandable Containers Impact the Accessible Experience

Any pattern that can show and hide content in a design must support the non-visual screen reading experience. Users must be able to perceive whether the content is expanded or collapsed, and users need to know where they can find the new expanded content.

The reading order of the expanded content must logically follow the target button controlling the content’s visibility for non-visual users to find and understand the content change. A non-visual screen reading experience is fundamentally linear, like reading a book.

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.

Anatomy

1. Leading Element (Optional): Avatar or System Icon.
2. Sub-Label (Optional): Additional text area for displaying further information in the header.
3. Divider (Optional): Used to separate container from other content.
4. Dynamic Body: Flexible body slot that expands and collapses.
5. Chevron: Dynamic system icon indicating collapsed and expanded states of the body content.
6. Container: Houses all elements.
7. Badge (Optional): Represents quantitative information centered against the Label and Sub-Label.
8. Label: Main header text.

Usage Guidance

Expandable hides information that may not be needed right away. Tapping on the header shows or hides content.

Collapsed content which is hidden by default should not be needed by users right away. Hiding needed actions or information critical to completion of a task can lead to user frustration.

Progressive Disclosure

Elements within the header should hint at the content to follow, so that users can make an informed choice about whether or not they want to see more details.

When to Use

Expandables are helpful to declutter a UI and focus user attention on more important details. Use an Expandable to:

• Hide content that isn’t needed right away, but may be helpful in a certain context.
• Keep an interface clutter-free and more manageable. If the amount of content on the screen is making it difficult to consume, consider hiding some of that content.
• Keep users in their current view, while remaining in context of a larger idea. Instead of navigating to another screen, Expandables help keep additional details directly related to the current screen.

When to Consider Something Else

• For tasks that require scanning and comparison, Lists better enable users to see more content at once. Having to expand and collapse separate containers to compare information can slow down and frustrate users.
• For folder or tree navigation, use a List with a trailing rightward chevron to redirect elsewhere. Expandables are used to show and hide content on the same screen — not for navigation.
• If action is required from the user to move along in a flow, consider surfacing that action using a Bottom Sheet or Alert Dialog instead. Avoid hiding tasks necessary for progression within an Expandable, as it may get lost.

Behaviors

Touch Targets

The entire surface area of the header is interactive. Tapping on the header expands or collapses the content area, showing or hiding more details. Elements within the header do not have an additional touch target. Elements contained in expandable content area may have their own touch targets.

States

Expandables support the default, pressed, and selected states in their headers, including when the container is expanded.

Examples

Trailing Chevron

By default, the container displays as collapsed. After pressing on the header, content expands outwards from the container, with the chevron rotating 180 degrees clockwise.

Leading Chevron

On larger screens like tablets, the icon is placed in the leading area of the container before any visuals or the label to prevent a large space between content and the affordance for expanding and collapsing. During expansion, the chevron rotates clockwise 90 degrees.

Optional Elements

Avatar

An Avatar may be placed in the leading area before the label.

Icon

A leading system icon may also be placed in the leading area before the label.

Badge

Badge may be used within Expandable to convey numerical information associated with the data being represented by the header.

Sub-Label

A sub-label may be used to supplement the main label in the header.

In Cards

Expandables may be used within Card for additional hierarchy and visual emphasis in the UI. Card can contain multiple or a single instance of Expandable.

Wrapping

Text does not automatically truncate in Expandable, so the main label and sub-label should ideally never exceed 3 lines of text.

Truncation may be set at any number of lines in both the main label and sub-label for closed Expandables. When open, however, all text will display, even if truncation has been set for the closed version.

Component API

Methods

Class name: ExpandableContainer Module name: UIComponentsPlugin

public init(
  featureData: FeatureMetricsData,
  title: String,
  subtitle: String? = nil,
  isExpanded: Bool = false,
 	leadingItem: ExpandableContainerLeadingItem? = nil,
 	badgeCount: Int? = nil,
 	titleLineLimit: Int? = nil,
  subtitleLineLimit: Int? = nil,
  semanticContext: State<SemanticContext> = .init(initialValue: .default),
  removePaddingOnHeader: Bool = false,
  showDivider: Bool = true,
  contentSpacing: CGFloat? = nil,
  localizer: LocalizationAdapting,
  @ViewBuilder content: @escaping () -> Content
)

Parameters

Content Guidelines

When writing content for an Expandable, please refer to the Expandable section of Content’s UI Text recommendations.

Anatomy

1. Leading Element (Optional): Avatar or System Icon.
2. Sub-Label (Optional): Additional text area for displaying further information in the header.
3. Divider (Optional): Used to separate container from other content.
4. Dynamic Body: Flexible body slot that expands and collapses.
5. Chevron: Dynamic system icon indicating collapsed and expanded states of the body content.
6. Container: Houses all elements.
7. Badge (Optional): Represents quantitative information centered against the Label and Sub-Label.
8. Label: Main header text.

Usage Guidance

Expandable hides information that may not be needed right away. Tapping on the header shows or hides content.

Collapsed content which is hidden by default should not be needed by users right away. Hiding needed actions or information critical to completion of a task can lead to user frustration.

Progressive Disclosure

Elements within the header should hint at the content to follow, so that users can make an informed choice about whether or not they want to see more details.

When to Use

Expandables are helpful to declutter a UI and focus user attention on more important details. Use an Expandable to:

• Hide content that isn’t needed right away, but may be helpful in a certain context.
• Keep an interface clutter-free and more manageable. If the amount of content on the screen is making it difficult to consume, consider hiding some of that content.
• Keep users in their current view, while remaining in context of a larger idea. Instead of navigating to another screen, Expandables help keep additional details directly related to the current screen.

When to Consider Something Else

• For tasks that require scanning and comparison, Lists better enable users to see more content at once. Having to expand and collapse separate containers to compare information can slow down and frustrate users.
• For folder or tree navigation, use a List with a trailing rightward chevron to redirect elsewhere. Expandables are used to show and hide content on the same screen — not for navigation.
• If action is required from the user to move along in a flow, consider surfacing that action using a Bottom Sheet or Alert Dialog instead. Avoid hiding tasks necessary for progression within an Expandable, as it may get lost.

Behaviors

Touch Targets

The entire surface area of the header is interactive. Tapping on the header expands or collapses the content area, showing or hiding more details. Elements within the header do not have an additional touch target. Elements contained in expandable content area may have their own touch targets.

States

Expandables support the default, pressed, and selected states in their headers, including when the container is expanded.

Examples

Trailing Chevron

By default, the container displays as collapsed. After pressing on the header, content expands outwards from the container, with the chevron rotating 180 degrees clockwise.

Leading Chevron

On larger screens like tablets, the icon is placed in the leading area of the container before any visuals or the label to prevent a large space between content and the affordance for expanding and collapsing. During expansion, the chevron rotates clockwise 90 degrees.

Optional Elements

Avatar

An Avatar may be placed in the leading area before the label.

Icon

A leading system icon may also be placed in the leading area before the label.

Badge

Badge may be used within Expandable to convey numerical information associated with the data being represented by the header.

Sub-Label

A sub-label may be used to supplement the main label in the header.

In Cards

Expandables may be used within Card for additional hierarchy and visual emphasis in the UI. Card can contain multiple or a single instance of Expandable.

Wrapping

Text does not automatically truncate in Expandable, so the main label and sub-label should ideally never exceed 3 lines of text.

Truncation may be set at any number of lines in both the main label and sub-label for closed Expandables. When open, however, all text will display, even if truncation has been set for the closed version.

Component API

@Composable
fun ExpandableContainerUiComponent(
    modifier: Modifier = Modifier,
    label: String,
    avatarConfig: ExpandableContainerAvatarConfig? = null,
    semanticState: SemanticState = SemanticState(),
    initiallyExpanded: Boolean = false,
    onExpandedStateChange: (expanded: Boolean) -> Unit = {},
    content: @Composable () -> Unit = {}
)

Props

Content Guidelines

When writing content for an Expandable, please refer to the Expandable section of Content’s UI Text recommendations.