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, place Expandable.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>
        This is a really long title that should wrap to multiple lines
      </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.

Note: If using an avatar image, do not also include an Icon component in addition to the Expandable.Icon. This component is meant to have either an avatar image or an icon in addition to the Expandable.Icon, or neither an avatar image nor an extra icon.

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>
);

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 {CanvasProvider} from '@workday/canvas-kit-react/common';
import {Expandable} from '@workday/canvas-kit-react/expandable';

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';
import {createStyles} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const expandableStyles = createStyles({
  boxShadow: system.depth[3],
  borderRadius: system.shape.lg,
  padding: system.padding.xs,
  margin: system.gap.xs,
});

export default () => {
  return (
    <Expandable cs={expandableStyles}>
      <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>
);

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

const listStyles = createStyles({
  flexDirection: 'column',
  gap: system.gap.sm,
  padding: '0',
  marginInline: system.padding.md,
  marginBlock: '0',
});

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 cs={{gap: system.gap.lg, flexDirection: 'column'}}>
      <Flex cs={{gap: system.gap.md}}>
        <SecondaryButton onClick={handleExpandAll}>Expand All</SecondaryButton>
        <SecondaryButton onClick={handleCollapseAll}>Collapse All</SecondaryButton>
      </Flex>
      <Flex cs={{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>
  );
};

For the accordion composition (named regions on each panel), see Accessibility Requirements.

Accessibility

Ensure users of assistive technology can find the control, understand whether related content is shown or hidden, and reveal or hide that content from the keyboard. Expandable is an inline disclosure (show/hide)  widget: a button toggles content that stays in the document flow.

Use Expandable for show/hide sections in the page. Compose multiple instances to build an accordion  — see Hoisted Model. For a navigation accordion, see Side Panel with Navigation .

Minimum Accessible Structure

The following matches the Start Icon example layout: Expandable.Icon before Expandable.Title inside Expandable.Target, then Expandable.Content. headingLevel is omitted here on purpose — add it only after asking which level matches the page outline (see Accessibility Requirements). The Basic Example code uses headingLevel="h4" as a sample, not a default.

import {Expandable} from '@workday/canvas-kit-react/expandable';
 
<Expandable>
  <Expandable.Target>
    <Expandable.Icon iconPosition="start" />
    <Expandable.Title>Title</Expandable.Title>
  </Expandable.Target>
  <Expandable.Content>Content</Expandable.Content>
</Expandable>;

Built-in Behaviors

Canvas Kit applies these automatically via useExpandableModel (a DisclosureModel) and Expandable subcomponents. Do not duplicate them in consuming code.

ARIA and DOM (applied by hooks/subcomponents):

• Expandable.Target: native <button> with aria-expanded (true when visibility !== 'hidden') and aria-controls set to the disclosure id. onClick toggles events.show() / events.hide().
• headingLevel: when set ('h1'–'h6'), wraps the button in Heading rendered as that heading element. When omitted, the button is not wrapped in a heading.
• Expandable.Content: id set to the same disclosure id. Collapsed content stays in the DOM with display: none (not unmounted). Default element is a <div>.
• Expandable.Title: styled <div> for the visible name. It does not receive an id from the model.
• Expandable.Icon: decorative chevron that rotates from visibility. Expanded/collapsed state for assistive technology comes from aria-expanded, not from the icon.
• Expandable.Avatar: isDecorative={true} by default so the image is hidden from assistive technology when paired with Expandable.Title.
• Disclosure id: generated with useUniqueId unless you pass id to useExpandableModel. Default initialVisibility is 'hidden'.

Keyboard (native button behavior):

Expandable.Target uses native <button> keyboard behavior (tab order, Enter /

Space to toggle). Collapsed content is not in the tab order (display: none). Focus stays on the button; Canvas Kit does not move focus into Expandable.Content.

Screen reader expectations (when built-in behaviors are used as intended):

• On focus, assistive technology announces the title text, the button role, and expanded/collapsed state from aria-expanded (for example, “Title, button, collapsed”)
• Activating the button announces the updated expanded/collapsed state from aria-expanded
• While collapsed, content is removed from the accessibility tree (display: none)
• While expanded, content follows the button in reading order
• When headingLevel is set, heading navigation includes the heading that wraps the button
• When Expandable.Content as="section" is used with aria-labelledby pointing at Expandable.Title, region/landmark navigation can name each open section

Accessibility Requirements

Required in application code for an accessible Expandable. Hoist useExpandableModel when you need programmatic show/hide (for example, expand all) or a stable disclosure id. Rows marked (conditional) apply only when the situation matches—otherwise omit.

If no design spec is provided: use the single disclosure composition (Basic Example). If the spec is several related headers, use the accordion composition. Omit Expandable.Avatar, initialVisibility, and a custom id.

Choose a composition (pick one; Expandable.Content as="section" and as="ul" are mutually exclusive):

• Single disclosure — one show/hide section. Basic Example / Minimum Accessible Structure. Default Content is a <div>.
• Accordion — several related headers. Hoisted Model: unique id on Expandable.Title, Expandable.Content as="section" with aria-labelledby.
• Navigation list — disclosed links. Side Panel with Navigation : as="ul", omit headingLevel.

Heading level: Ask which heading (h1–h6) belongs in the document outline before setting headingLevel. Omit headingLevel for navigation. Do not generate headingLevel by default — the Basic Example code uses h4 only as a sample.

Summary for code generation:

• REQUIRED: Expandable.Target, non-empty Expandable.Title, Expandable.Content, Expandable.Icon
• CONDITIONAL: composition (single disclosure vs accordion vs navigation list), headingLevel (ask which; omit for navigation), accordion as="section" + aria-labelledby, navigation as="ul", Expandable.Avatar, hoisted useExpandableModel, initialVisibility

Anti-Patterns

Do not generate code that does the following (see Accessibility Requirements above for what to supply instead):

• Manually set aria-expanded, aria-controls, or the disclosure id on Expandable.Target or Expandable.Content — useExpandableTarget and useExpandableContent wire these
• Rely on Expandable.Icon or Expandable.Avatar for the accessible name — use Expandable.Title
• Override Expandable.Target with a custom as — Expandable.Target already renders a native <button>
• Set id on Expandable to identify the outer wrapper — id is model config and is forwarded to the container element, while Expandable.Content also uses state.id, which can produce duplicate IDs. For a stable content id, hoist useExpandableModel({id: '…'}). Expandable.Title still needs its own id when you set aria-labelledby on Expandable.Content
• Wrap Expandable.Target in your own heading — use headingLevel instead
• Default headingLevel to h4 (or any level) without asking, or set headingLevel on navigation disclosures
• Generate several Basic Example disclosures with default div Content when the spec is an accordion — use the accordion composition (see Choose a composition)
• Set as="section" and as="ul" on the same Expandable.Content — pick one composition
• Change Expandable.Title to encode state (for example “Collapsed” / “Expanded” or “Show” / “Hide”) — aria-expanded already exposes state
• Unmount Expandable.Content when collapsed, or add aria-hidden on it — the library uses display: none
• Set isDecorative={false} on Expandable.Avatar by default, or pair an avatar with an extra non-chevron icon
• Use open, expanded, or onToggle props on Expandable — visibility is initialVisibility plus useExpandableModel events
• Assume default Expandable.Content is a landmark region — that is only true with as="section"

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>
)

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.