StackView
- Library
- UDS Base
- Repository
- github.com/telus/universal-design-system
- Package
- npmjs.com/package/@telus-uds/ds-allium
- Package version
- 1.14.0
Introduction
import { StackView } from '@telus-uds/ds-allium'
StackView puts space evenly between its children.
Guidance
Use StackView to create layouts with simple, neat, even spacing.
- If a layout requires different spacing between different items, use
Spacer. - If the items need to wrap if they exceed a fixed size, use
StackWrap. - For space around an element or group of elements, wrap them in a
Box. - For more complex grids designed using a Bootstrap-like 12-column-grid system, consider
FlexGrid.
space prop
The space prop sets the size of spacing between items, using the spacing scale.
Simple numbers may be used, or objects (see spacing scale docs for details. These examples change spacing depending on the viewport.
direction prop
By default, items are stacked vertically as a flex column. Pass direction as 'row' to stack horizontally.
This applies flexDirection: 'row' styles to the container and passes appropriate props to spacers.
Directions of row-reverse and column-reverse may be used to reverse the visual display of the stacked children.
The direction prop may also be passed a responsive object keyed by viewports.
divider prop
By default, space is created by inserting a <Spacer> component between children.
If the divider prop is passed as true, children are instead spaced with a Divider.
The StackView's space prop value is passed down to these dividers, rendering spacers before and after the dividing line.
direction is applied to dividers automatically.
The divider prop may take an object of Divider props, which are passed to the rendered dividers.
Composition notes
StackView only spaces rendered, direct children. This means common React composition patterns may be used without
needing to worry about creating spurious spacing:
- Comments and nullish children can be safely used and are ignored when spacing is inserted
- Fragments may be used when composing children, items within a fragment will still be spaced
This example demonstrates how StackView responds to various common React composition patterns:
Accessibility
By default, StackView applies no accessibility props or values relevant to accessibility tools. It may accept React Native accessibility props (web docs, native docs), and applies them to the outer container.
Semantic divider
If the divider prop is used, on Web, accessibility tools will be aware that a semantic separator exists between elements.
Tag prop for semantic HTML
By default, StackView renders a <div> on web and a View with no accessibility role on native apps.
To render a HTML attribute with a semantic meaning on web, pass a string naming a HTML semantic layout tag
to the tag prop. An accessibilityRole may also be passed if a role is needed in native apps.
Heading tags (h1, h2, h3, h4, h5, h6) are by default mapped to "heading" role in native apps.
See the tag entry in the props table for the full list of supported tags.
Platform considerations
The component is available on both native platforms and web.
Props
| Name | Type | Default | Description |
|---|---|---|---|
| children | node | A StackView may take any children, but will have no effect if it is only passed one child or is passed children wrapped in a component. If necessary, children may be wrapped in one React Fragment. | |
| direction | responsiveProps .getTypeOptionallyByViewport( PropTypes.oneOf(['column', 'row', 'column-reverse', 'row-reverse']) ) | 'column' | Sets the 'flexDirection' of the container and, if 'divider' is used, gives the Divider the appropriate direction. |
| divider | bool | { tokens, space, variant, vertical: bool } | If true, renders a UDS 'Divider' component between each item. If an object is passed, this object is passes as props to each Divider. | |
| space | spacingIndexPropType | spacingObjectPropType | 1 | The size of the spacer according to the theme's spacing scale. Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc), or, a SpacingObject with viewport keys and options (see 'useSpacingScale' for details). |
| tag | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'article' | 'aside' | 'blockquote' | 'footer' | 'figure' | 'form' | 'header' | 'ul' | 'li' | 'main' | 'nav' | 'section' | 'label' | Optional semantic HTML tag, to apply to the container on web. Does not change styling. In native apps, if a header tag is provided ("h1", "h2" etc) and accessibilityRole prop is not defined, the accessibilityRole will default to "heading". | |
| 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 | alignItems | flexAlign |
| justifyContent | flexJustifyContent | |
| flexGrow | integer | |
| flexShrink | integer |
Variants
This component does not have any stylistic variants.
To control flex alignment and positioning, the tokens prop may be passed an object to apply the flex layout styles 'alignItems', 'justifyContent', 'flexShrink' and 'flexGrow'.
As always with the tokens prop, this should be used only where strictly necessary to avoid creating off-brand layouts.
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