ExpandCollapse

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/components-base

Package version

1.6.1

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/components-base'

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

Loading...

function ExpandCollapseControlledExample() { const [open, setOpen] = React.useState([]) const closeAll = () => setOpen([]) return ( <StackView space={3}> {open.length > 0 ? ( <StackView direction="row" tokens={{ justifyContent: 'space-between' }}> <Typography>Panels open: {open.join(', ')}.</Typography> <TextButton onPress={closeAll}>Close all panels</TextButton> </StackView> ) : ( <Typography>No panels open.</Typography> )} <ExpandCollapse open={open} onChange={setOpen}> {(expandProps) => ( <StackView divider={{ variant: { decorative: true } }}> <ExpandCollapse.Panel {...expandProps} panelId="first" control={<Typography>First panel</Typography>} > <Typography>First panel content</Typography> </ExpandCollapse.Panel> <ExpandCollapse.Panel {...expandProps} panelId="second" control={<Typography>Second panel</Typography>} > <Typography>Second panel content</Typography> </ExpandCollapse.Panel> <ExpandCollapse.Panel {...expandProps} panelId="third" control={<Typography>Third panel</Typography>} > <Typography>Third panel content</Typography> </ExpandCollapse.Panel> </StackView> )} </ExpandCollapse> </StackView> ) }

function ExpandCollapseControlledExample() {
  const [open, setOpen] = React.useState([])
  const closeAll = () => setOpen([])
  return (
    <StackView space={3}>
      {open.length > 0 ? (
        <StackView direction="row" tokens={{ justifyContent: 'space-between' }}>
          <Typography>Panels open: {open.join(', ')}.</Typography>
          <TextButton onPress={closeAll}>Close all panels</TextButton>
        </StackView>
      ) : (
        <Typography>No panels open.</Typography>
      )}
      <ExpandCollapse open={open} onChange={setOpen}>
        {(expandProps) => (
          <StackView divider={{ variant: { decorative: true } }}>
            <ExpandCollapse.Panel
              {...expandProps}
              panelId="first"
              control={<Typography>First panel</Typography>}
            >
              <Typography>First panel content</Typography>
            </ExpandCollapse.Panel>
            <ExpandCollapse.Panel
              {...expandProps}
              panelId="second"
              control={<Typography>Second panel</Typography>}
            >
              <Typography>Second panel content</Typography>
            </ExpandCollapse.Panel>
            <ExpandCollapse.Panel
              {...expandProps}
              panelId="third"
              control={<Typography>Third panel</Typography>}
            >
              <Typography>Third panel content</Typography>
            </ExpandCollapse.Panel>
          </StackView>
        )}
      </ExpandCollapse>
    </StackView>
  )
}

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

Props

Name	Type	Default	Description
variant	objectOf		System variant prop, see variants for more details
tokens	custom		System tokens prop, see tokens for more details
children*	union		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>`
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.
open	arrayOf		If passed, the item or items that are expanded will be controlled by a parent component
onChange	func		Function called when which panels are currently open changes. Necessary if `open` is passed.
initialOpen	arrayOf		Allows items with specified ids to be open by default on first load. Should not be used with `open`.