Cloaked Design SystemLayout
VStack
A vertical flex column with a token-scale gap, cross-axis alignment, main-axis distribution, wrap, and scroll options.
Implementation previewCOMPLETE STORYBOOK REFERENCE
7 storiesEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Playground selectedOpen canvas
Example source
packages/design-system/src/components/layout/VStack/VStack.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A vertical flex column with a token-scale gap, cross-axis alignment, main-axis distribution, wrap, and scroll options.
Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { VStack } from '@cloakedinc/design-system';VStackStackOwnProps
packages/design-system/src/components/layout/VStack/VStack.tsx:14
| Prop | Type | Presence | Notes |
|---|---|---|---|
gap | 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined | Optional | Space between children, in `--cds-space-*` steps. |
align | StackAlign | undefined | Optional | Cross-axis alignment (`align-items`). |
justify | StackJustify | undefined | Optional | Main-axis distribution (`justify-content`). |
wrap | boolean | undefined | Optional | Reflow children onto new lines on overflow, where `scroll` keeps them on one line. |
scroll | boolean | undefined | Optional | Turn the stack into a swipeable overflow strip on the main axis (HStack scrolls horizontally, VStack vertically) and hide the scrollbar. For carousels, set `scroll-snap-align` on the children. |
as | React.ElementType<any, keyof React.JSX.IntrinsicElements> | undefined | Optional | Rendered element. Defaults to `div`. |
className | string | undefined | Optional | |
style | React.CSSProperties | undefined | Optional | |
children | React.ReactNode | Optional | |
testId | string | undefined | Optional | Optional test selector, placed on the `as` element. |
id | string | undefined | Optional | DOM id for aria relationships such as `aria-describedby`. |
padding | 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined | Optional | Padding on all four sides. |
paddingX | 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined | Optional | Horizontal padding (left + right). Overrides `padding` on the X axis. |
paddingY | 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined | Optional | Vertical padding (top + bottom). Overrides `padding` on the Y axis. |
paddingTop | 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined | Optional | Top padding. Overrides `paddingY` and `padding`. |
paddingRight | 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined | Optional | Right padding. Overrides `paddingX` and `padding`. |
paddingBottom | 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined | Optional | Bottom padding. Overrides `paddingY` and `padding`. |
paddingLeft | 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined | Optional | Left padding. Overrides `paddingX` and `padding`. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
Vertical flex column with a token-scale gap — the default replacement for hand-rolled
display:flex; flex-direction:column wrappers. It is the most-reached-for layout primitive.
When to use
Reach for VStack any time you stack elements top to bottom with consistent spacing — form
fields, list rows, card contents, whole screen bodies. align is the cross (horizontal) axis
and justify the main (vertical) axis, so justify="between" pushes the first and last child
to the top and bottom edges.
- Laying out a row left to right? Use
HStack. - Placing items in equal-width tiles across a fixed column count? Use
Grid. - Scaffolding a whole route (surface, safe-area insets, sticky header/footer)? Wrap the page
in
Screenand useVStackfor the content inside it. - Need a surface behind a centered panel without route chrome? Use
Background.
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- root
- Label
- Root
- Description
- Flex column container. Structural: it lays out children and paints no surface of its own.
- Required
- true
Allowed Design Choices
- Variants
- Column
- Label
- Column
- Description
- The single vertical flex layout.
- Sizes
- Alignments
- Start
- Label
- Start
- Center
- Label
- Center
- End
- Label
- End
- Stretch
- Label
- Stretch
- Baseline
- Label
- Baseline
- Justifications
- Start
- Label
- Start
- Center
- Label
- Center
- End
- Label
- End
- Between
- Label
- Between
- Around
- Label
- Around
- Evenly
- Label
- Evenly
Variants
- Id
- column
- Label
- Column
- Description
- Vertical flex container.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- stack-gap
- Label
- Column gap
- Kind
- example-only
- Token
- --cds-space-12
- Value
- 12
- Unit
- px
- Applies To
- root
- Notes
- Representative value: gap is author-configurable and accepts any step on the spacing scale. 12 is the value rendered and verified by the Playground story.
Layout
- Alignment
- align sets the cross (horizontal) axis; justify sets the main (vertical) axis.
- Flow
- Children flow top to bottom and may wrap or scroll on overflow.
- Notes
- Use HStack for a row, Grid for equal-width tiles, and Screen/Background for full-screen scaffolding.
Typography And Color
- Typography
- Label
- Inherited
- Description
- VStack sets no type; children own their text. Ramp noted for parity.
- Token
- --cds-type-body-size
- Colors
- Label
- Transparent
- Description
- VStack paints no background; the surface behind shows through.
- Token
- --cds-bg-page
States
- Id
- default
- Label
- Default
- Description
- Static column that flexes to its children.
- Id
- wrap
- Label
- Wrapped
- Description
- Children wrap onto additional columns on overflow.
- Id
- scroll
- Label
- Scroll
- Description
- The column becomes a vertical overflow region with a hidden scrollbar.
Behavior
- Label
- Token gap
- Description
- gap uses the spacing scale; avoid hand-rolled flex wrappers.
- Label
- Padding
- Description
- Padding props map to the spacing scale per edge.
Accessibility
- Label
- Presentational
- Description
- VStack is a layout container and adds no roles; order follows DOM order.
- Label
- Focus order
- Description
- Reordering visually via justify does not change tab order.
Content Adaptation
- Label
- Wrap vs scroll
- Description
- Choose wrap to reflow onto new columns or scroll to keep a single overflow region.
- Label
- Distribution
- Description
- between, around, and evenly pin content to the top and bottom edges of a sized column.
Motion Haptics
- Motion
- Label
- None
- Description
- VStack does not animate layout changes on its own.
- Haptics
- Label
- None
- Description
- A layout container requests no haptics.