ExpandCollapse

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/ds-allium

Package version

1.14.0

Loading...

<ExpandCollapse> {(expandProps) => ( <StackView divider space={2}> <ExpandCollapse.Panel {...expandProps} panelId="first" control={<Typography variant={{ size: 'h4' }}>First panel</Typography>} > <Typography>Some content within the first panel</Typography> </ExpandCollapse.Panel> <ExpandCollapse.Panel {...expandProps} panelId="second" control={<Typography variant={{ size: 'h4' }}>Second panel</Typography>} > <Typography>Some content within the second panel</Typography> </ExpandCollapse.Panel> <Box space={3} left={6}> <Typography>Non-interactive item</Typography> </Box> <ExpandCollapse.Panel {...expandProps} panelId="third" control={<Typography variant={{ size: 'h4' }}>Last panel</Typography>} > <Typography>Some content within the last panel</Typography> </ExpandCollapse.Panel> <Spacer space={0} /> </StackView> )} </ExpandCollapse>

<ExpandCollapse>
  {(expandProps) => (
    <StackView divider space={2}>
      <ExpandCollapse.Panel
        {...expandProps}
        panelId="first"
        control={<Typography variant={{ size: 'h4' }}>First panel</Typography>}
      >
        <Typography>Some content within the first panel</Typography>
      </ExpandCollapse.Panel>
      <ExpandCollapse.Panel
        {...expandProps}
        panelId="second"
        control={<Typography variant={{ size: 'h4' }}>Second panel</Typography>}
      >
        <Typography>Some content within the second panel</Typography>
      </ExpandCollapse.Panel>
      <Box space={3} left={6}>
        <Typography>Non-interactive item</Typography>
      </Box>
      <ExpandCollapse.Panel
        {...expandProps}
        panelId="third"
        control={<Typography variant={{ size: 'h4' }}>Last panel</Typography>}
      >
        <Typography>Some content within the last panel</Typography>
      </ExpandCollapse.Panel>
      <Spacer space={0} />
    </StackView>
  )}
</ExpandCollapse>

Introduction

import { ExpandCollapse } from '@telus-uds/ds-allium'

Flexible base component for lists where some or all items are collapsible headers.

Guidance

ExpandCollapse is designed for flexibility - components for a particular interaction pattern can be built on top of it. SideNav is an example of a component built on top of ExpandCollapse that facilitates a particular interaction pattern.

ExpandCollapse

The outer ExpandCollapse represents the container for one or more collapsible ExpandCollapse.Panels and manages state on which panels are open and closed.

Children

ExpandCollapse takes a render function as its child and passes it an object, expandProps, which can be spread onto any ExpandCollapse.Panels. These don't need to be direct children and can be anywhere inside the ExpandCollapse container.

Any number or arrangment of non-expandable items may be included alongside expandable panels.

Loading...

<ExpandCollapse> {(expandProps) => ( <StackView space={3}> <Box space={2} variant={{ background: 'light' }}> <ExpandCollapse.Panel {...expandProps} panelId="first" control={<Typography>First panel</Typography>} > <Typography>Some content within the first panel</Typography> </ExpandCollapse.Panel> </Box> <Box space={2} variant={{ background: 'light' }}> <ExpandCollapse.Panel {...expandProps} panelId="second" control={<Typography>Second panel</Typography>} > <Typography>Some content within the second panel</Typography> </ExpandCollapse.Panel> </Box> <Box space={4} variant={{ background: 'light' }}> <Typography>Some non-expandable content</Typography> </Box> </StackView> )} </ExpandCollapse>

<ExpandCollapse>
  {(expandProps) => (
    <StackView space={3}>
      <Box space={2} variant={{ background: 'light' }}>
        <ExpandCollapse.Panel
          {...expandProps}
          panelId="first"
          control={<Typography>First panel</Typography>}
        >
          <Typography>Some content within the first panel</Typography>
        </ExpandCollapse.Panel>
      </Box>
      <Box space={2} variant={{ background: 'light' }}>
        <ExpandCollapse.Panel
          {...expandProps}
          panelId="second"
          control={<Typography>Second panel</Typography>}
        >
          <Typography>Some content within the second panel</Typography>
        </ExpandCollapse.Panel>
      </Box>
      <Box space={4} variant={{ background: 'light' }}>
        <Typography>Some non-expandable content</Typography>
      </Box>
    </StackView>
  )}
</ExpandCollapse>

maxOpen prop

By default, any number of items may be opened at once. If desired, a number may be passed to ExpandCollapse's maxItems props to pin it only allow that many items to be open at a time.

The Accordion component is a shorthand for ExpandCollapse with maxOpen set as 1.

initialOpen prop

An array of panel Ids may be passed to the initialOpen prop to set those panels as open by default.

Loading...

<ExpandCollapse maxOpen={2} initialOpen={['first', 'second']}> {(expandProps) => ( <StackView divider={{ variant: { decorative: true } }}> <ExpandCollapse.Panel {...expandProps} panelId="first" control={<Typography>First panel</Typography>} > <Typography>Some content within the first panel</Typography> </ExpandCollapse.Panel> <ExpandCollapse.Panel {...expandProps} panelId="second" control={<Typography>Second panel</Typography>} > <Typography>Some content within the second panel</Typography> </ExpandCollapse.Panel> <ExpandCollapse.Panel {...expandProps} panelId="third" control={<Typography>Third panel</Typography>} > <Typography>Some content within the third panel</Typography> </ExpandCollapse.Panel> </StackView> )} </ExpandCollapse>

<ExpandCollapse maxOpen={2} initialOpen={['first', 'second']}>
  {(expandProps) => (
    <StackView divider={{ variant: { decorative: true } }}>
      <ExpandCollapse.Panel
        {...expandProps}
        panelId="first"
        control={<Typography>First panel</Typography>}
      >
        <Typography>Some content within the first panel</Typography>
      </ExpandCollapse.Panel>
      <ExpandCollapse.Panel
        {...expandProps}
        panelId="second"
        control={<Typography>Second panel</Typography>}
      >
        <Typography>Some content within the second panel</Typography>
      </ExpandCollapse.Panel>
      <ExpandCollapse.Panel
        {...expandProps}
        panelId="third"
        control={<Typography>Third panel</Typography>}
      >
        <Typography>Some content within the third panel</Typography>
      </ExpandCollapse.Panel>
    </StackView>
  )}
</ExpandCollapse>

Controlled behaviour with open prop

An ExpandCollapse may be controlled by a parent by passing an array of panel IDs to its open prop and a function that updates state to onChange. When delegating responsibility to the parent like this, initialOpen prop should not be used and open should always be defined as an array (pass an empty array when nothing is open).

ExpandCollapse.Panel

Each section that may be opened and closed should be wrapped in an ExpandCollapse.Panel and the expandProps from the ExpandCollapse parent should be spread to each of these.

panelId prop (required)

Every ExpandCollapse.Panel must also take a panelId prop. This string will be used by the ExpandCollapse parent to manage whether this panel is open or closed.

Note that unlike HTML element id attributes, this does not need to be unique on the page. It is only used in the scope of the one ExpandCollapse parent. It should normally be unique within this one ExpandCollapse parent. If a panel id was to appear more than once, opening and closing each panel with the shared ID would open all others with the same ID.

control prop (required)

The control prop contains the rendered content in the pressable section that opens and closes the panel.

The icon and spacing around this content are controlled by the theme, which may be overridden by passing the panel a controlTokens object, for example, controlTokens={{ icon: null }} removes the panel's control's icon.

Accessibility

An ExpandCollapse panel's control is announced to assistive technology as a button with platform-appropriate notification of its expanded state automatically applied (aria-expanded on web and React Native's accessibilityState.expanded applied in native apps).

Platform considerations

ExpandCollapse is available on both web and native apps.

Props

Name	Type	Default	Description
children*	func | node		ExpandCollapse usually takes a render function to which it passes an object with properties { openIds, onToggle, resetValues, setValues, unsetValues }. openIds (array of ids) and onToggle (function) will usually be passed to '<ExpandCollapse.Panel>'
initialOpen	Array<string>		Allows items with specified ids to be open by default on first load. Should not be used with 'open'.
maxOpen	number		If set, enforces a specific maximum number of open items, closing already-open items when new items are opened. By default, any number of items may be open at once.
onChange	func		Function called when which panels are currently open changes. Necessary if 'open' is passed.
open	Array<string>		If passed, the item or items that are expanded will be controlled by a parent component
tokens	custom		System tokens prop, see tokens for more details
variant	objectOf		System variant prop, see variants for more details

Tokens

In exceptional circumstances, the following tokens can be passed to this component to override its default styles. Do not do this unless absolutely necessary. Read more about overriding styles.

View Tokens

Prop Name	Token Property	Token Type
tokens	borderColor	color
	borderWidth	border
	borderStyle	borderStyle

Figma

Variants

ExpandCollapse has no stylistic variants.

Feedback

• Spotted a problem with this component? Raise an issue on GitHub
• See any existing issues for this component
• Contact the team on slack in #ds-allium-support