Cloaked Design SystemLayout
HStack
A horizontal flex row with a token-scale gap, cross-axis alignment, main-axis distribution, wrap, and scroll options.
Implementation previewCOMPLETE STORYBOOK REFERENCE
6 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/HStack/HStack.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 horizontal flex row 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 { HStack } from '@cloakedinc/design-system';HStackStackOwnProps
packages/design-system/src/components/layout/HStack/HStack.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
Horizontal flex row with a token-scale gap — the default replacement for hand-rolled
display:flex; flex-direction:row wrappers.
When to use
Reach for HStack when items sit side by side in a single row — an icon beside a label, a
title with a trailing action, a footer's paired buttons. align is the cross (vertical) axis
and justify the main (horizontal) axis, so justify="between" pins the first and last child
to the row edges.
- Stacking elements top to bottom instead? Use
VStack. - Laying out equal-width tiles that wrap into a fixed column count? Use
Grid. - Row that overflows and should swipe? Use
scrollfor a plain overflow strip, orCarouselfor snapping one-per-view paging.
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- root
- Label
- Root
- Description
- Flex row container. Structural: it lays out children and paints no surface of its own.
- Required
- true
Allowed Design Choices
- Variants
- Row
- Label
- Row
- Description
- The single horizontal 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
- row
- Label
- Row
- Description
- Horizontal flex container.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- stack-gap
- Label
- Row 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 (vertical) axis; justify sets the main (horizontal) axis.
- Flow
- Children flow left to right and may wrap or scroll on overflow.
- Notes
- Use VStack for a column, Grid for equal-width tiles, and scroll or Carousel for a swipe strip.
Typography And Color
- Typography
- Label
- Inherited
- Description
- HStack sets no type; children own their text. Ramp noted for parity.
- Token
- --cds-type-body-size
- Colors
- Label
- Transparent
- Description
- HStack paints no background; the surface behind shows through.
- Token
- --cds-bg-page
States
- Id
- default
- Label
- Default
- Description
- Static row that flexes to its children.
- Id
- wrap
- Label
- Wrapped
- Description
- Children wrap onto additional rows on overflow.
- Id
- scroll
- Label
- Scroll
- Description
- The row becomes a horizontal overflow strip 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
- HStack 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 rows or scroll to keep a single overflow strip.
- Label
- Distribution
- Description
- between, around, and evenly need free space to distribute children.
Motion Haptics
- Motion
- Label
- None
- Description
- HStack does not animate layout changes on its own.
- Haptics
- Label
- None
- Description
- A layout container requests no haptics.