Stack

Flexbox stacking primitives. Stack is a thin flex container with typed direction, align, justify, and gap props — no more reaching for raw flex flex-col gap-* utilities. VStack and HStack are convenience wrappers that pin the direction (and sensible defaults) so the common cases read at a glance.

All three ship together and share one prop surface (StackProps). Anything not covered by the typed props — width, padding, background, flex-wrap — goes through className.

VStack

VStack stacks children in a column (flex-col). It defaults to align="stretch" and gap={2}, so children fill the cross axis and sit two spacing units apart unless you say otherwise.

First

Second

Third

import { VStack } from "@vesyl/ui-next";

function Box({ children }: { children: React.ReactNode }) {
  return (
    <div className="rounded-md bg-muted px-4 py-2 text-center text-sm font-medium">
      {children}
    </div>
  );
}

export default function StackVStack() {
  return (
    <VStack gap={3} className="w-full max-w-xs mx-auto">
      <Box>First</Box>
      <Box>Second</Box>
      <Box>Third</Box>
    </VStack>
  );
}

HStack

HStack lays children out in a row (flex-row). It defaults to align="center" and gap={2} — matching the way you almost always want an icon-and-label or a button row to behave.

First

Second

Third

import { HStack } from "@vesyl/ui-next";

function Box({ children }: { children: React.ReactNode }) {
  return (
    <div className="rounded-md bg-muted px-4 py-2 text-center text-sm font-medium">
      {children}
    </div>
  );
}

export default function StackHStack() {
  return (
    <HStack gap={3} justify="center">
      <Box>First</Box>
      <Box>Second</Box>
      <Box>Third</Box>
    </HStack>
  );
}

Stack with explicit direction

Reach for the base Stack when the direction is dynamic or you want it spelled out. direction is "vertical" (the default) or "horizontal"; VStack / HStack are just Stack with this prop locked in.

direction="vertical" (default)

One

Two

Three

direction="horizontal"

One

Two

Three

import { Stack } from "@vesyl/ui-next";

function Box({ children }: { children: React.ReactNode }) {
  return (
    <div className="rounded-md bg-muted px-4 py-2 text-center text-sm font-medium">
      {children}
    </div>
  );
}

export default function StackDirection() {
  return (
    <Stack gap={6} className="w-full">
      <Stack gap={2}>
        <span className="text-xs text-muted-foreground">direction="vertical" (default)</span>
        <Stack direction="vertical" gap={2}>
          <Box>One</Box>
          <Box>Two</Box>
          <Box>Three</Box>
        </Stack>
      </Stack>
      <Stack gap={2}>
        <span className="text-xs text-muted-foreground">direction="horizontal"</span>
        <Stack direction="horizontal" gap={2}>
          <Box>One</Box>
          <Box>Two</Box>
          <Box>Three</Box>
        </Stack>
      </Stack>
    </Stack>
  );
}

Gap

gap is a number mapped to a Tailwind gap-* class. The supported steps are 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, and 24 — a value outside this set produces no gap class. (A string is accepted by the type but only resolves if it matches one of those keys.)

gap=2

One

Two

Three

gap=4

One

Two

Three

gap=8

One

Two

Three

import { HStack, VStack } from "@vesyl/ui-next";

function Box({ children }: { children: React.ReactNode }) {
  return (
    <div className="rounded-md bg-muted px-4 py-2 text-center text-sm font-medium">
      {children}
    </div>
  );
}

export default function StackGap() {
  return (
    <VStack gap={6} className="w-full">
      {[2, 4, 8].map((gap) => (
        <VStack key={gap} gap={1}>
          <span className="text-xs text-muted-foreground">gap={gap}</span>
          <HStack gap={gap}>
            <Box>One</Box>
            <Box>Two</Box>
            <Box>Three</Box>
          </HStack>
        </VStack>
      ))}
    </VStack>
  );
}

Align and justify

align sets cross-axis alignment (items-*): "start", "center", "end", or "stretch". On an HStack this controls vertical alignment of children of differing heights.

align="start"

Short

Tall

Medium

align="center"

Short

Tall

Medium

align="end"

Short

Tall

Medium

align="stretch"

Short

Tall

Medium

import { HStack, VStack } from "@vesyl/ui-next";

function Box({ children, className }: { children: React.ReactNode; className?: string }) {
  return (
    <div
      className={`rounded-md bg-muted px-4 text-center text-sm font-medium leading-none flex items-center justify-center ${className ?? ""}`}
    >
      {children}
    </div>
  );
}

export default function StackAlign() {
  const aligns = ["start", "center", "end", "stretch"] as const;
  return (
    <VStack gap={6} className="w-full">
      {aligns.map((align) => (
        <VStack key={align} gap={1}>
          <span className="text-xs text-muted-foreground">align="{align}"</span>
          <HStack gap={3} align={align} className="h-24 rounded-md border border-dashed p-2">
            <Box className="py-2">Short</Box>
            <Box className="py-6">Tall</Box>
            <Box className="py-4">Medium</Box>
          </HStack>
        </VStack>
      ))}
    </VStack>
  );
}

justify sets main-axis distribution (justify-*): "start", "center", "end", "between", "around", or "evenly".

justify="start"

One

Two

Three

justify="center"

One

Two

Three

justify="end"

One

Two

Three

justify="between"

One

Two

Three

justify="around"

One

Two

Three

justify="evenly"

One

Two

Three

import { HStack, VStack } from "@vesyl/ui-next";

function Box({ children }: { children: React.ReactNode }) {
  return (
    <div className="rounded-md bg-muted px-4 py-2 text-center text-sm font-medium">
      {children}
    </div>
  );
}

export default function StackJustify() {
  const justifies = ["start", "center", "end", "between", "around", "evenly"] as const;
  return (
    <VStack gap={6} className="w-full">
      {justifies.map((justify) => (
        <VStack key={justify} gap={1}>
          <span className="text-xs text-muted-foreground">justify="{justify}"</span>
          <HStack gap={2} justify={justify} className="w-full rounded-md border border-dashed p-2">
            <Box>One</Box>
            <Box>Two</Box>
            <Box>Three</Box>
          </HStack>
        </VStack>
      ))}
    </VStack>
  );
}

Reference

Stack, VStack, and HStack all share StackProps, which also extends React.HTMLAttributes<HTMLDivElement> — so any standard div attribute (id, onClick, style, …) passes through.

Stack

The base container. Renders a div by default.

Prop	Type	Default	Description
`direction`	`"vertical" \| "horizontal"`	`"vertical"`	Flex direction (`flex-col` / `flex-row`)
`align`	`"start" \| "center" \| "end" \| "stretch"`	—	Cross-axis alignment (`items-*`)
`justify`	`"start" \| "center" \| "end" \| "between" \| "around" \| "evenly"`	—	Main-axis distribution (`justify-*`)
`gap`	`number \| string`	—	Gap between items. Supported: `0`–`6`, `8`, `10`, `12`, `16`, `20`, `24`
`as`	`React.ElementType`	`"div"`	Render as a different element
`className`	`string`	—	Merged after the variant + gap classes
`ref`	`React.Ref<HTMLDivElement>`	—	Forwarded to the rendered element

VStack

Stack locked to a column. Accepts every StackProps field except direction.

Prop	Type	Default	Description
`align`	`"start" \| "center" \| "end" \| "stretch"`	`"stretch"`	Cross-axis alignment
`gap`	`number \| string`	`2`	Gap between items (same scale as `Stack`)

HStack

Stack locked to a row. Accepts every StackProps field except direction.

Prop	Type	Default	Description
`align`	`"start" \| "center" \| "end" \| "stretch"`	`"center"`	Cross-axis alignment
`gap`	`number \| string`	`2`	Gap between items (same scale as `Stack`)