Stack

Vertical and horizontal layout stacks with even spacing between items. Children can reveal in order, and adding or removing items smoothly moves the rest into place.

Preview

TSX components/ui/stack/stack.tsx

import * as React from "react";
import { forwardRef } from "react";
import { View, type ViewProps, type FlexAlignType, type ViewStyle } from "react-native";
import Animated, { FadeIn, FadeOut, LinearTransition } from "react-native-reanimated";
import { BAND_STAGGER, SwitchOn, cn, rowDelay, spring, timing, useReducedMotion } from "@lumioui/core";

/**
 * Stack — layout primitives.
 *   <VStack gap={12} align="center">…</VStack>
 *   <HStack gap={8} justify="between">…</HStack>
 *   <Spacer />
 *   <Box className="p-4">…</Box>
 *
 * Opt-in switch-on (DESIGN-TASTE §5c rule 6):
 *   <VStack reveal="bands">…</VStack>   each direct child switches on 120ms apart
 *   <VStack reveal="rows">…</VStack>    40ms apart, capped at 300ms
 *   <VStack animateLayout>…</VStack>    inserts ignite, removals dim, the rest reflow
 * Without these props a stack is a plain View — nothing is wrapped.
 */

type Align = "start" | "center" | "end" | "stretch" | "baseline";
type Justify = "start" | "center" | "end" | "between" | "around" | "evenly";

const alignMap: Record<Align, FlexAlignType> = {
  start: "flex-start",
  center: "center",
  end: "flex-end",
  stretch: "stretch",
  baseline: "baseline",
};

const justifyMap: Record<Justify, ViewStyle["justifyContent"]> = {
  start: "flex-start",
  center: "center",
  end: "flex-end",
  between: "space-between",
  around: "space-around",
  evenly: "space-evenly",
};

export interface StackProps extends ViewProps {
  /** Gap between children in px (applied via style for reliability). */
  gap?: number;
  /** Cross-axis alignment. */
  align?: Align;
  /** Main-axis distribution. */
  justify?: Justify;
  className?: string;
  /**
   * Switch each direct child on as the stack mounts: children start dim
   * (readable) with a 6px rise and brighten in order — "bands" on the 120ms
   * page rhythm, "rows" on the 40ms list rhythm (capped at 300ms). Each
   * child is wrapped in its own view, so `flex-1` children should carry
   * their sizing on an outer element. Reduced motion keeps the brightening.
   */
  reveal?: "bands" | "rows";
  /**
   * Inserted children ignite in place, removed children dim out, and the
   * siblings reflow on `spring.layout`. Children are wrapped like `reveal`.
   */
  animateLayout?: boolean;
}

/** Exits dim on the recede beat; inserts ignite on the fast one. */
const ENTER = FadeIn.duration(timing.fast.duration);
const EXIT = FadeOut.duration(timing.recede.duration);

/** True once the stack has mounted — children that appear after it are inserts. */
function useMounted(enabled: boolean) {
  const [mounted, setMounted] = React.useState(false);
  // Plain stacks never re-render for this.
  React.useEffect(() => {
    if (enabled) setMounted(true);
  }, [enabled]);
  return mounted;
}

/** One wrapped child. Its delay is fixed at mount so a later reorder never re-dims it. */
function StackItem({
  delay,
  late,
  reveal,
  animateLayout,
  children,
}: {
  delay: number;
  late: boolean;
  reveal: boolean;
  animateLayout: boolean;
  children: React.ReactNode;
}) {
  const reduce = useReducedMotion();
  // An insert ignites at once; children present at mount keep their place in the order.
  const [insert] = React.useState(late);
  const [startAt] = React.useState(late ? 0 : delay);
  const inner = reveal ? <SwitchOn delay={startAt}>{children}</SwitchOn> : children;
  if (!animateLayout) return <>{inner}</>;
  return (
    <Animated.View
      entering={insert ? ENTER : undefined}
      exiting={EXIT}
      layout={reduce ? undefined : LinearTransition.springify().damping(spring.layout.damping).stiffness(spring.layout.stiffness)}
    >
      {inner}
    </Animated.View>
  );
}

/** Wraps direct children only when a motion prop asks for it. */
function wrapChildren(
  children: React.ReactNode,
  reveal: StackProps["reveal"],
  animateLayout: boolean | undefined,
  mounted: boolean
) {
  if (!reveal && !animateLayout) return children;
  const items = React.Children.toArray(children).map((child, i) => (
    <StackItem
      key={React.isValidElement(child) && child.key != null ? child.key : i}
      delay={reveal === "bands" ? i * BAND_STAGGER : rowDelay(i)}
      late={mounted}
      reveal={reveal != null}
      animateLayout={!!animateLayout}
    >
      {child}
    </StackItem>
  ));
  return items;
}

export const VStack = forwardRef<React.ElementRef<typeof View>, StackProps>(
  function VStack({ gap, align, justify, className, style, reveal, animateLayout, children, ...props }, ref) {
    const mounted = useMounted(!!reveal || !!animateLayout);
    const content = wrapChildren(children, reveal, animateLayout, mounted);
    return (
      <View
        ref={ref}
        className={cn("flex-col", className)}
        // Consumer style first — explicit gap/align/justify props come last
        // so they always win over className utilities and inline style.
        style={[
          style,
          gap != null && { gap },
          align != null && { alignItems: alignMap[align] },
          justify != null && { justifyContent: justifyMap[justify] },
        ]}
        {...props}
      >
        {content}
      </View>
    );
  }
);

export const HStack = forwardRef<React.ElementRef<typeof View>, StackProps>(
  function HStack({ gap, align, justify, className, style, reveal, animateLayout, children, ...props }, ref) {
    const mounted = useMounted(!!reveal || !!animateLayout);
    const content = wrapChildren(children, reveal, animateLayout, mounted);
    return (
      <View
        ref={ref}
        className={cn("flex-row", className)}
        // Same precedence as VStack: explicit props beat style and className.
        style={[
          style,
          gap != null && { gap },
          align != null && { alignItems: alignMap[align] },
          justify != null && { justifyContent: justifyMap[justify] },
        ]}
        {...props}
      >
        {content}
      </View>
    );
  }
);

export const Spacer = forwardRef<React.ElementRef<typeof View>, ViewProps & { className?: string }>(
  function Spacer({ className, ...props }, ref) {
    return (
      <View
        ref={ref}
        className={cn("flex-1", className)}
        accessibilityElementsHidden
        importantForAccessibility="no"
        aria-hidden
        {...props}
      />
    );
  }
);

export const Box = forwardRef<React.ElementRef<typeof View>, ViewProps & { className?: string }>(
  function Box({ className, ...props }, ref) {
    return <View ref={ref} className={cn(className)} {...props} />;
  }
);

VStack.displayName = "VStack";
HStack.displayName = "HStack";
Spacer.displayName = "Spacer";
Box.displayName = "Box";

TSX example.tsx

import { Stack } from "@/components/ui/stack/stack";

export function Example() {
  return (
    <Stack />
  );
}

Installation

npx @lumioui/cli add stack

Install the dependencies
npx expo install react-native-reanimated
Copy the source from the Code tab into your project
components/ui/stack/stack.tsxcomponents/ui/stack/index.ts
Update the import paths to match your project setup.

Usage

import { VStack, HStack, Spacer, Box } from "@/components/ui/stack/stack";

<Stack />

Also exported: VStack, HStack, Spacer, Box.

Examples

Box

Box surfaces composing a parcel-tracking card: product, status, a four-step track and an action row.

npx @lumioui/cli add stack-box

TSX components/ui/stack/variants/box.tsx

import * as React from "react";
import { Pressable, type LayoutChangeEvent } from "react-native";
import Animated, {
  Easing,
  runOnJS,
  useAnimatedStyle,
  useSharedValue,
  withSpring,
  withTiming,
} from "react-native-reanimated";
import { ease, spring, timing, useReducedMotion } from "@lumioui/core";
import { Box } from "../stack";
import { Icon, type IconName } from "../../icon/icon";
import { Image } from "../../image/image";
import { Text } from "../../text/text";

const STEPS = ["Ordered", "Shipped", "Out for delivery", "Delivered"];

/** The light head leading a filling segment. */
const HEAD = 12;
const FILL = { ...timing.slow, easing: Easing.bezier(...ease.out) };
const DIM = { ...timing.recede, easing: Easing.bezier(...ease.in) };
const IGNITE = { ...timing.fast, easing: Easing.bezier(...ease.out) };

/** One leg of the track. Reaching it fills from the left behind a bright head;
 *  the body runs a little dim while the head travels, then switches fully on. */
function Segment({ on }: { on: boolean }) {
  const reduce = useReducedMotion();
  const w = useSharedValue(0);
  const fill = useSharedValue(on ? 1 : 0);
  const body = useSharedValue(1);
  const head = useSharedValue(0);
  // Only real changes animate — mount (and a strict-mode re-run) shows the resting state.
  const last = React.useRef(on);
  React.useEffect(() => {
    if (last.current === on) return;
    last.current = on;
    if (!on) {
      // Leaving: dim in place, never un-fill.
      body.value = withTiming(0, DIM, (f) => {
        if (f) fill.value = 0;
      });
      return;
    }
    if (reduce) {
      fill.value = 1;
      body.value = 0;
      body.value = withTiming(1, IGNITE);
      return;
    }
    fill.value = 0;
    body.value = 0.7;
    head.value = 1;
    fill.value = withTiming(1, FILL, (f) => {
      if (!f) return;
      head.value = withTiming(0, DIM);
      body.value = withTiming(1, IGNITE);
    });
  }, [on, reduce, fill, body, head]);
  const fillStyle = useAnimatedStyle(() => ({
    opacity: body.value,
    transform: [{ translateX: (fill.value - 1) * w.value }],
  }));
  const headStyle = useAnimatedStyle(() => ({
    opacity: head.value,
    transform: [{ translateX: fill.value * w.value - HEAD }],
  }));
  return (
    <Box
      className="h-1 flex-1 overflow-hidden rounded-full bg-muted"
      onLayout={(e: LayoutChangeEvent) => {
        w.value = e.nativeEvent.layout.width;
      }}
    >
      <Animated.View className="absolute inset-0 rounded-full bg-primary" style={fillStyle} />
      <Animated.View className="absolute bottom-0 top-0 rounded-full bg-primary" style={[{ width: HEAD }, headStyle]} />
    </Box>
  );
}

/** A line that swaps in place: the old text dims, the new one ignites with a 4px rise. */
function SwapText({ children, className, variant }: { children: string; className?: string; variant?: "muted" }) {
  const reduce = useReducedMotion();
  const [shown, setShown] = React.useState(children);
  const o = useSharedValue(1);
  const y = useSharedValue(0);
  const s = useSharedValue(1);
  React.useEffect(() => {
    if (children === shown) return;
    o.value = withTiming(0, DIM, (f) => {
      if (f) runOnJS(setShown)(children);
    });
    if (!reduce) s.value = withTiming(0.96, DIM);
  }, [children, shown, reduce, o, s]);
  const lastShown = React.useRef(shown);
  React.useEffect(() => {
    if (lastShown.current === shown) return;
    lastShown.current = shown;
    o.value = withTiming(1, IGNITE);
    if (reduce) return;
    y.value = 4;
    y.value = withSpring(0, spring.swap);
    s.value = withSpring(1, spring.swap);
  }, [shown, reduce, o, y, s]);
  const style = useAnimatedStyle(() => ({ opacity: o.value, transform: [{ translateY: y.value }, { scale: s.value }] }));
  return (
    <Animated.View style={[{ transformOrigin: "left" }, style]}>
      <Text className={className} variant={variant}>
        {shown}
      </Text>
    </Animated.View>
  );
}

/** StackBox — Box surfaces composing a parcel-tracking card: product,
 *  status, a four-step track and an action row. "Delivered" is reachable —
 *  tap the status line to advance the parcel: the next leg fills behind a
 *  light head while the status swaps in place. Neutral ink. */
export function StackBox() {
  const [step, setStep] = React.useState(2);
  const done = step === STEPS.length - 1;
  const actions: [IconName, string][] = done
    ? [["star", "Review"], ["refresh", "Return"], ["message-circle", "Help"]]
    : [["map-pin", "Track"], ["calendar", "Reschedule"], ["message-circle", "Help"]];
  return (
    <Box className="w-full gap-5 rounded-3xl bg-card p-5">
      <Box className="flex-row items-center gap-3">
        <Image
          source={{ uri: "https://images.unsplash.com/photo-1560769629-975ec94e6a86?w=200&h=200&fit=crop&q=70&auto=format" }}
          rounded="xl"
          className="h-16 w-16 bg-muted"
          alt="Colour-block trainers"
        />
        <Box className="flex-1">
          <Text className="text-[17px] font-semibold">Prism runner, size 10</Text>
          <Text variant="muted">Order #LM-30417 · Parcelwise</Text>
        </Box>
      </Box>

      <Pressable
        onPress={() => setStep((s) => (s + 1) % STEPS.length)}
        accessibilityRole="button"
        accessibilityLabel={`Status: ${STEPS[step]}`}
        className="gap-3"
      >
        <Box className="gap-1">
          <SwapText className="text-2xl font-bold tracking-tight">
            {done ? "Delivered" : step === 2 ? "Arriving today" : STEPS[step]!}
          </SwapText>
          <SwapText variant="muted">
            {done ? "Left at front door · 2:14 PM" : step === 2 ? "By 8 PM · 6 stops away" : "Estimated Thu, Oct 9"}
          </SwapText>
        </Box>
        <Box className="flex-row gap-1">
          {STEPS.map((s, i) => (
            <Segment key={s} on={i <= step} />
          ))}
        </Box>
      </Pressable>

      <Box className="flex-row border-t border-border pt-3">
        {actions.map(([icon, label]) => (
          <Pressable
            key={label}
            className="h-14 flex-1 items-center justify-center gap-1"
            accessibilityRole="button"
            accessibilityLabel={label}
          >
            <Icon name={icon} size="md" color="foreground" />
            <Text className="text-[13px] font-medium">{label}</Text>
          </Pressable>
        ))}
      </Box>
    </Box>
  );
}

Hstack

HStack + Spacer laying out a watchlist: logo, name, then the price pushed to the trailing edge.

npx @lumioui/cli add stack-hstack

TSX components/ui/stack/variants/hstack.tsx

import * as React from "react";
import { Pressable, View } from "react-native";
import Animated, { Easing, runOnJS, useAnimatedStyle, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
import { ease, spring, timing, useHaptic, useReducedMotion } from "@lumioui/core";
import { HStack, Spacer, VStack } from "../stack";
import { Text } from "../../text/text";

const WATCH = [
  { sym: "ORBT", name: "Orbital", price: 227.48, pct: 1.24, tile: "bg-muted", ink: "text-foreground" },
  { sym: "VYKO", name: "Vyko Robotics", price: 131.06, pct: -2.11, tile: "bg-tint-green", ink: "text-white" },
  { sym: "MRDN", name: "Meridian", price: 84.92, pct: 3.47, tile: "bg-tint-lime", ink: "text-white" },
  { sym: "BRSL", name: "Bristle", price: 412.3, pct: 0.38, tile: "bg-tint-green", ink: "text-white" },
];

const DIM = { ...timing.recede, easing: Easing.bezier(...ease.in) };
const IGNITE = { ...timing.fast, easing: Easing.bezier(...ease.out) };
/** Units change, not the value — a short 4px rise says "new reading". */
const SWAP_RISE = 4;

/** The change figure swaps in place: the old reading dims, the new one ignites. */
function Delta({ text, className }: { text: string; className: string }) {
  const reduce = useReducedMotion();
  const [shown, setShown] = React.useState(text);
  const o = useSharedValue(1);
  const y = useSharedValue(0);
  const s = useSharedValue(1);
  React.useEffect(() => {
    if (text === shown) return;
    o.value = withTiming(0, DIM, (f) => {
      if (f) runOnJS(setShown)(text);
    });
    if (!reduce) s.value = withTiming(0.96, DIM);
  }, [text, shown, reduce, o, s]);
  const last = React.useRef(shown);
  React.useEffect(() => {
    if (last.current === shown) return;
    last.current = shown;
    o.value = withTiming(1, IGNITE);
    if (reduce) return;
    y.value = SWAP_RISE;
    y.value = withSpring(0, spring.swap);
    s.value = withSpring(1, spring.swap);
  }, [shown, reduce, o, y, s]);
  const style = useAnimatedStyle(() => ({ opacity: o.value, transform: [{ translateY: y.value }, { scale: s.value }] }));
  return (
    <Animated.View style={[{ transformOrigin: "right" }, style]}>
      <Text className={className}>{shown}</Text>
    </Animated.View>
  );
}

/** StackHStack — HStack + Spacer laying out a watchlist: logo, name, then
 *  the price pushed to the trailing edge. Tap any change pill to flip all
 *  of them between % and $; each figure dims and the new reading ignites in
 *  place. The rows switch on 40ms apart through `reveal="rows"`. */
export function StackHStack() {
  const haptics = useHaptic();
  const [asDollars, setAsDollars] = React.useState(false);
  return (
    <VStack gap={8} className="w-full">
      <HStack align="end" className="px-1">
        <Text className="text-2xl font-bold tracking-tight">Watchlist</Text>
        <Spacer />
        <Text variant="muted">Market open</Text>
      </HStack>
      <VStack reveal="rows" className="overflow-hidden rounded-2xl bg-card">
        {WATCH.map((w, i) => {
          const up = w.pct >= 0;
          const delta = asDollars
            ? `${up ? "+" : "−"}$${Math.abs((w.price * w.pct) / 100).toFixed(2)}`
            : `${up ? "+" : "−"}${Math.abs(w.pct).toFixed(2)}%`;
          return (
            <HStack
              key={w.sym}
              gap={12}
              align="center"
              className={`px-4 py-3 ${i > 0 ? "border-t border-border" : ""}`}
            >
              <View className={`h-10 w-10 items-center justify-center rounded-full ${w.tile}`}>
                <Text className={`text-xs font-bold ${w.ink}`}>{w.sym.slice(0, 2)}</Text>
              </View>
              <VStack>
                <Text className="text-base font-semibold">{w.sym}</Text>
                <Text variant="muted">{w.name}</Text>
              </VStack>
              <Spacer />
              <VStack align="end" gap={4}>
                <Text className="text-base font-medium tabular-nums">${w.price.toFixed(2)}</Text>
                <Pressable
                  onPress={() => {
                    haptics.selection();
                    setAsDollars((d) => !d);
                  }}
                  hitSlop={8}
                  accessibilityRole="button"
                  accessibilityLabel={`${w.sym} change ${delta}. Tap to show ${asDollars ? "percent" : "dollars"}`}
                  className={`min-w-[72px] items-end rounded-md px-2 py-1 ${up ? "bg-success/15" : "bg-destructive/15"}`}
                >
                  <Delta text={delta} className={`text-[13px] font-semibold tabular-nums ${up ? "text-success" : "text-destructive"}`} />
                </Pressable>
              </VStack>
            </HStack>
          );
        })}
      </VStack>
    </VStack>
  );
}

Vstack

A centred VStack as a creator profile header: avatar, name, bio, stats, then actions in an HStack.

npx @lumioui/cli add stack-vstack

TSX components/ui/stack/variants/vstack.tsx

import * as React from "react";
import { Image } from "react-native";
import { Accent } from "@lumioui/core";
import { HStack, VStack } from "../stack";
import { Button } from "../../button/button";
import { Icon } from "../../icon/icon";
import { Text } from "../../text/text";

/** StackVStack — a centred VStack as a creator profile header: avatar,
 *  name, bio, stats, then actions in an HStack. Follow is live and the
 *  follower count answers. Coral for social. */
export function StackVStack() {
  const [following, setFollowing] = React.useState(false);
  const followers = 18240 + (following ? 1 : 0);
  return (
    <Accent color="coral" className="w-full">
      <VStack align="center" gap={16} className="w-full rounded-3xl bg-card px-5 py-6">
        <Image
          source={{ uri: "https://i.pravatar.cc/150?img=47" }}
          className="h-24 w-24 rounded-full bg-muted"
          accessibilityIgnoresInvertColors
        />
        <VStack align="center" gap={4}>
          <Text className="text-2xl font-bold tracking-tight">Noor Haddad</Text>
          <Text variant="muted">@noorbakes · Amman</Text>
        </VStack>
        <Text className="text-center text-[15px] leading-snug">
          Sourdough, cardamom buns and slow Sunday bakes. New recipe every Friday.
        </Text>
        <HStack justify="center" gap={32}>
          {[
            [followers.toLocaleString("en-US"), "Followers"],
            ["312", "Following"],
            ["96", "Recipes"],
          ].map(([v, l]) => (
            <VStack key={l} align="center">
              <Text className="text-lg font-semibold tabular-nums">{v}</Text>
              <Text className="text-xs text-muted-foreground">{l}</Text>
            </VStack>
          ))}
        </HStack>
        <HStack gap={8} className="w-full">
          <Button
            className="flex-1"
            variant={following ? "secondary" : "default"}
            onPress={() => setFollowing((f) => !f)}
          >
            {following ? "Following" : "Follow"}
          </Button>
          <Button className="flex-1" variant="secondary">
            Message
          </Button>
          <Button
            size="icon"
            variant="secondary"
            accessibilityLabel="More options"
            icon={<Icon name="more-horizontal" size="sm" color="foreground" />}
          />
        </HStack>
      </VStack>
    </Accent>
  );
}

API reference

Prop Type Default

gap number

Gap between children in px (applied via style for reliability).

—

align Align

Cross-axis alignment.

—

justify Justify

Main-axis distribution.

—

className string —

reveal "bands" | "rows"

Switch each direct child on as the stack mounts: children start dim (readable) with a 6px rise and brighten in order — "bands" on the 120ms page rhythm, "rows" on the 40ms list rhythm (capped at 300ms). Each child is wrapped in its own view, so flex-1 children should carry their sizing on an outer element. Reduced motion keeps the brightening.

—

animateLayout boolean

Inserted children ignite in place, removed children dim out, and the siblings reflow on spring.layout. Children are wrapped like reveal.

—

Primitives

Composed

Screens