Expandable Container

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

GitHub Storybook Figma

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

Sources

GitHub Storybook Figma

Install

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

Anatomy

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.'
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.
Title: The heading text for the information being shown in the content section.
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.

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.

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.

Depth

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.

You can also have direct access to the model if

Hoisted Model

If you 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.

Component API

Expandable

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

Layout Component

Expandable supports all props from thelayout component.

Props

Props extend from div. Changing the as prop will change the element interface.

Props extend from . If a model is passed, props from ExpandableModelConfig are ignored.

Name	Type	Description	Default
`children`	`ReactNode`	The children of the `Expandable` container. This should contain `Expandable.Target` and `Expandable.Container`
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`div`
`ref`	`React.Ref<R = div>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

Expandable.Target

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.

Layout Component

Expandable.Target supports all props from thelayout component.

Props

Props extend from button. Changing the as prop will change the element interface.

Name	Type	Description	Default
`children`	`ReactNode`	Children of the `Expandable.Target`. Should contain `Target.Title`, an optional `Target.Avatar` and `Target.Icon` with an `iconPosition` prop that takes a value of either `start` or `end`. `Target.Icon` with `start` is meant to be placed before the `Target.Title` and `Target.Icon` `end` should be placed after.
`headingLevel`	`'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'`	This specifies the semantic heading level that will wrap the `Expandable.Target`'s button. If not defined, then nothing will wrap the button.
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`button`
`ref`	`React.Ref<R = button>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

useExpandableTarget

(
  model: , 
  elemProps: {}, 
  ref: React.Ref
) => {
  aria-controls: string;
  aria-expanded: boolean;
  onClick: (event: ) => void;
}

Expandable.Title

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

Layout Component

Expandable.Title supports all props from thelayout component.

Props

Props extend from div. Changing the as prop will change the element interface.

Name	Type	Description	Default
`children`	`ReactNode`	Children of the `Expandable.Title`. This should contain a string for the title
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`div`
`ref`	`React.Ref<R = div>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).

Expandable.Icon

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.

Layout Component

Expandable.Icon supports all props from thelayout component.

Props

Props extend from span. Changing the as prop will change the element interface.

Name	Type	Description	Default
`icon`		Icon to display from `@workday/canvas-accent-icons-web`
`iconPosition`		Button icon positions can either be `start` or `end`. If no value is provided, it defaults to `start`.	`'start'`
`fill`		The fill color of the SystemIcon. This overrides `color`.
`color`		The color of the SystemIcon. This defines `accent` and `fill`. `color` may be overriden by `accent` and `fill`.
`size`	`number \| string \| undefined`	The size of the SystemIcon in `px`.
`styles`
`shouldMirror`	`boolean`	If set to `true`, transform the SVG's x-axis to mirror the graphic	`false`
`background`		The background color of the SystemIcon.
`children`	`ReactNode`
`accent`		The accent color of the SystemIcon. This overrides `color`.
`accentHover`		The accent color of the SystemIcon on hover. This overrides `colorHover`.
`backgroundHover`		The background color of the SystemIcon on hover.
`colorHover`		The hover color of the SystemIcon. This defines `accentHover` and `fillHover`. `colorHover` may be overriden by `accentHover` and `fillHover`.
`fillHover`		The fill color of the SystemIcon on hover. This overrides `colorHover`.
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`span`
`ref`	`React.Ref<R = span>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

useExpandableIcon

(
  model: , 
  elemProps: {}, 
  ref: React.Ref
) => {
  visible: boolean;
}

Expandable.Avatar

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

Props

Props extend from button. Changing the as prop will change the element interface.

Name	Type	Description	Default
`variant`		The variant of the Avatar default state. Accepts `Light` or `Dark`.
`ref`	`Ref<>`
`size`	`\| number`	The size of the Avatar.
`objectFit`	`Property.ObjectFit`	The object-fit CSS property sets how the content of a replaced element, such as an `<img>` or `<video>`, should be resized to fit its container. See object-fit. If your image is not a square, you can use this property to ensure the image is rendered properly.
`altText`	`string`	The alt text of the Avatar image. This prop is also used for the aria-label
`url`	`string`	The url of the Avatar image.
`children`	`React.ReactNode`
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`button`
`ref`	`React.Ref<R = button>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).

Expandable.Content

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.

Layout Component

Expandable.Content supports all props from thelayout component.

Props

Props extend from div. Changing the as prop will change the element interface.

Name	Type	Description	Default
`children`	`ReactNode`	The children of the `Expandable.Content` whose visibility is controlled by the associated `Expandable.Target`
`as`	`React.ElementType`	Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef`and spread extra props to a root element. Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.	`div`
`ref`	`React.Ref<R = div>`	Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
`model`		Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
`elemPropsHook`	`( model: , elemProps: TProps ) => HTML Attributes`	Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.

useExpandableContent

(
  model: , 
  elemProps: {}, 
  ref: React.Ref
) => {
  style:  {
      display: undefined;
    }  | {
      display: string;
    };
  id: string;
}

Model

useExpandableModel

The ExpandableModel extends the DisclosureModel

useExpandableModel (config: ):

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.

Figma

Sources

Figma

Anatomy

Container
Expandable Header: Contains a label, chevron, and optional leading element.
Lead Content (Optional): Optional leading visual element, such as an Avatar or Icon.
Chevron: Icon indicating the opened or closed state of the container by pointing in the direction of expansion.
Content Slot: Expandable area where users can find more information on the container's subject.
Divider: Separates expandable container from other elements.

Usage Guidance

Expandable Containers are used to hide information that may not be needed right away. Tapping on the header reveals content as requested.

Touch Targets

The entire surface area of the header is interactive. Tapping on the header will expand or collapse the content area, revealing or hiding more details. Any elements within the header should not have an additional touch target; however, elements within the expandable content may be tappable.

Keep a parallel structure.

Don't

Don't enables touch targets for elements within the header, such as the Avatar.

Aid in Decision Making

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.

Labels and supporting visuals should be directly related to the expandable content, the expanded content should not be a surprise.

Don't

Don't use supporting visuals purely for decoration - they should tie directly to the content.

Disclosure Icons

On mobile devices, a downward facing chevron is placed at the end of the header to indicate a collapsed state. When expanding, the icon rotates 180 degrees clockwise until content is fully displayed.
For tablets, a leading rightward icon is used,rotating 90 degrees clockwise instead.
The same chevron icon is rotated on expansion for both expanded and collapsed states, rather than a different chevron icon for expanded and collapsed states.

Hiding Content

Make sure that collapsed content (i.e., hidden by default) isn’t needed by users right away. Hiding needed actions or information critical to completion of a task can be lead to frustration.

Use Expandable Containers to hide non-critical information that may not be needed immediately

Don't

Hide critical information or actions in the content area

When to Use

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

Hide content that isn’t needed right away, but may be helpful in a certain context.
To 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.
To keep users in their current view, while remaining in context of a larger idea. Instead of navigating to another screen, Expandable Containers help keep additional details directly related to the current screen.

When to Use Something Else

For tasks that require scanning and comparison, it may be more important 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. Expandable Containers 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 Sheet or Alert Dialog instead. Avoid hiding tasks necessary for progression within an Expandable Container, as it may get lost.

Behaviors

State

Expandable Containers have the default, pressed, and selected states. The default and pressed state are only applied to the header.

States are available on the header when the Expandable Container is expanded.

Default: Interactive
Pressed: Is being pressed
Disabled: Non-interactive

Examples

End Icon

By default, 'ExpandableContainerUiComponent' is set to be collapsed. After pressing on the header, 'Expandable. Content'should expand outwards from the container, with the chevron rotating 180 degrees clockwise until expanded.

Start Icon

On larger screens like tablets, the icon is placed at start of the container before any visuals or the label. During expansion, the chevron rotates clockwise 90 degrees until the content is fully expanded

Avatar

To include an Avatar, place 'ExpandableContainerUIComponent.avatarConfig' between Expandable.Chevron and Expandable.Label. The Avatar will be placed before the label.

Icon

A leading system icon may be used instead.

Styled

Expandable may use tokens to adjust the visual styling of the component.

Text Wrap

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

Accordion

By default, Expandable Containers remain expanded until the user chooses to collapse the panel. You can hoist the models to expand and collapse all three containers at once.

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

Name	Type	Default	Description
label	`String`	None	Text shown on the expandable container.
avatarConfig	`ExpandableContainerAvatarConfig`	null	Optional avatar config for the container. Will only be used in the normal semantic state.
semanticState	`SemanticState`	SemanticState()	Adjusts the state of the Component. This allows for enabling, disabling, warning, error, and required states.
initiallyExpanded	`Boolean`	false	Initial expanded state of the container. Defaults to collapsed.
onExpandedStateChange	`(expanded: Boolean) -> Unit`	{}	Optional lambda to execute when we expand or collapse the container.
content	`@Composable () -> Unit`	{}	Content slot for content that shows up below the title when expanded.

Accessibility Guidelines

Coming soon...

Content Guidelines

Coming soon...

Can't Find What You Need?

Check out our FAQ section which may help you find the information you're looking for. For further information, contact the #canvas or #canvas-kitchannels on Slack.

FAQ Section

Expandable Container

Anatomy

Usage Guidance

When to Use

When to Use Something Else

Examples

Start Icon

End Icon

With Avatar

Title

Right to Left (RTL)

Depth

Additional Information

Title Wrap

Our house special supreme pizza includes pepperoni, sausage, bell peppers, mushrooms, onions, and oregano.

Hoisted Model

Usage Guidance

Accessibility Guidelines

Content Guidelines

Component API

Expandable

Layout Component

Props

Expandable.Target

Layout Component

Props

useExpandableTarget

Expandable.Title

Layout Component

Props

Expandable.Icon

Layout Component

Props

useExpandableIcon

Expandable.Avatar

Props

Expandable.Content

Layout Component

Props

useExpandableContent

Model

useExpandableModel

Accessibility Guidelines

Content Guidelines

Anatomy

Usage Guidance

Touch Targets

Aid in Decision Making

Disclosure Icons

Hiding Content

When to Use

When to Use Something Else

Behaviors

State

Examples

End Icon

Start Icon

Avatar

Icon

Styled

Text Wrap

Accordion

Component API

Accessibility Guidelines

Content Guidelines

Anatomy

Usage Guidance

Touch Targets

Aid in Decision Making

Disclosure Icons

Hiding Content

When to Use

When to Use Something Else