Stack

Playground

Installation

pnpm add @tessinaui/ui

Usage

import { Stack, HStack, VStack } from "@tessinaui/ui";

{/* Vertical stack (default) */}
<Stack gap="md">
  <div>First</div>
  <div>Second</div>
  <div>Third</div>
</Stack>

{/* Horizontal row */}
<Stack direction="horizontal" gap="sm" align="center">
  <Avatar src="/me.png" />
  <div>
    <p className="font-medium">Jane Doe</p>
    <p className="text-muted-foreground">jane@example.com</p>
  </div>
</Stack>

{/* Convenience wrappers */}
<HStack gap="sm">…</HStack>
<VStack gap="md">…</VStack>

{/* Dividers between items */}
<Stack
  direction="horizontal"
  align="center"
  divider={<span className="w-px self-stretch bg-border" />}
>
  <span>Home</span>
  <span>Products</span>
  <span>About</span>
</Stack>

{/* Wrapping with reverse order */}
<Stack direction="horizontal" wrap reverse gap="sm">
  {tags.map((t) => <Chip key={t}>{t}</Chip>)}
</Stack>

{/* Polymorphic — render as <nav> */}
<Stack
  direction="horizontal"
  gap="sm"
  render={<nav aria-label="Primary" />}
>
  <a href="/">Home</a>
  <a href="/about">About</a>
</Stack>

{/* RTL */}
<Stack direction="horizontal" dir="rtl" gap="sm">
  <span>أول</span>
  <span>ثاني</span>
  <span>ثالث</span>
</Stack>

Showcase

Direction

Switch between a column and a row with direction.

Combine with reverse to flip item order.

Gap

Controls the spacing between items (and between items and dividers when present).

Align (cross-axis)

Maps to flex align-items. In a vertical stack, this controls the horizontal alignment of children.

Justify (main-axis)

Maps to flex justify-content.

Wrap

wrap={true} enables flex-wrap so items fall to a new line when the container cannot fit them on the main axis. Useful for chip groups, tag clouds, or responsive toolbars.

Divider

Pass any node to divider to render it between each child. Stack handles the interleaving — you just describe the separator.

<Stack
  direction="horizontal"
  align="center"
  gap="md"
  divider={<span className="w-px self-stretch bg-border" />}
>
  <span>Alpha</span>
  <span>Beta</span>
  <span>Gamma</span>
</Stack>

For vertical stacks, render a horizontal rule instead:

<Stack
  gap="md"
  divider={<span className="h-px self-stretch bg-border" />}
>…</Stack>

Inline

inline={true} swaps flex for inline-flex so the stack can sit inline with surrounding text or flow alongside other inline-block elements.

HStack and VStack

Direction-locked convenience wrappers that preserve the full API otherwise.

<HStack gap="sm">…</HStack>  {/* direction="horizontal" */}
<VStack gap="md">…</VStack>  {/* direction="vertical" */}

They accept every Stack prop except direction.

Polymorphic render

Keep Stack styling while swapping the underlying element for semantic HTML.

<Stack direction="horizontal" gap="sm" render={<nav aria-label="Primary" />}>
  <a href="/">Home</a>
  <a href="/about">About</a>
</Stack>

<Stack gap="sm" render={<ul />}>
  <li>First</li>
  <li>Second</li>
</Stack>

The passed element's existing className is merged with Stack's generated classes, and its own children (if any) are preserved over the Stack's children.

RTL

dir="rtl" flips the main-axis direction of horizontal stacks and is forwarded to the underlying element. Per-component dir means you can mix LTR and RTL stacks on the same page without changing the global document direction.

Accessibility

• Stack is a structural layout primitive — it does not apply any ARIA roles on its own.

• Use render to wrap semantic HTML (<nav>, <ul>, <section>, <header>) when the grouping has meaning. Keep <div> (the default) for purely presentational arrangements.

• Dividers are cosmetic. Mark them as aria-hidden so they are not announced by screen readers:

  divider={<span aria-hidden className="w-px self-stretch bg-border" />}

• focus-visible rings on Stack's children remain visible because Stack sets no overflow clipping.

API Reference

Stack Props

HStack / VStack

Both accept every prop above except direction, which is locked to "horizontal" and "vertical" respectively.

Notes

• Default direction is vertical. This matches the convention of most React layout primitives (Chakra, Radix Themes) and reads naturally in JSX where children are typed top-to-bottom.
• align="stretch" is the default. In a column, children expand to fill the horizontal width. Switch to "start", "center", or "end" to let children size themselves.
• Divider interleaving uses React.Children.toArray, so keyed lists (.map() output) work without warnings — Stack assigns its own keys to the divider fragments.
• render precedence: when passed, Stack renders the provided element type with its original props merged in, its original className concatenated with Stack's generated classes, and its original children (if any) preserved over the Stack's children.
• No SSR caveats. Stack is a pure layout primitive with no hooks beyond useMemo for divider interleaving — safe to render on the server.