Grid

Grid with a set number of equal-width columns, adjustable gaps and styling for each cell. Cells can optionally fade in one after another in reading order.

Preview

TSX components/ui/grid/grid.tsx

import * as React from "react";
import { forwardRef, Children } from "react";
import { View, type ViewProps } from "react-native";
import { cn, rowDelay, SwitchOn } from "@lumioui/core";

/**
 * Grid — simple responsive grid via flexbox wrap.
 *   <Grid columns={3} gap={12}>
 *     <Card /><Card /><Card />
 *   </Grid>
 * Children are auto-wrapped in equal-width cells.
 *
 * Opt-in `cascade`: cells start dim (still readable) and switch on in
 * reading order on the tile rhythm (40ms apart, capped at 300ms) with a
 * 6px rise — Lumio's "things switch on". Reduced motion keeps the light,
 * drops the rise. Without it the grid renders plain, exactly as before.
 */

export interface GridProps extends ViewProps {
  /** Number of columns. Default 2. */
  columns?: number;
  /** Gap between cells in px. */
  gap?: number;
  className?: string;
  /** Extra classes for each cell wrapper. */
  cellClassName?: string;
  /** Cells switch on in reading order at mount (dim → on, 40ms apart). Default false. */
  cascade?: boolean;
  /** Wait before the first cell switches on, in ms — to follow a header band. Default 0. */
  cascadeDelay?: number;
  children?: React.ReactNode;
}

export const Grid = forwardRef<React.ElementRef<typeof View>, GridProps>(
  function Grid(
    { columns = 2, gap = 0, className, cellClassName, cascade = false, cascadeDelay = 0, children, style, ...props },
    ref
  ) {
    const cols = Number.isFinite(columns) ? Math.max(1, Math.floor(columns)) : 2;
    const items = Children.toArray(children);
    // Each cell takes an equal share of the row minus its share of the gap.
    const cellWidth = `${100 / cols}%` as const;

    return (
      <View
        ref={ref}
        // accessibilityRole lacks "grid"/"gridcell" — the `role` prop is the
        // typed path (RNW forwards it as the ARIA role). "cell" is RN's
        // closest mapping for gridcell.
        role="grid"
        className={cn("w-full flex-row flex-wrap", className)}
        // Explicit `gap` prop wins over a className gap-*: `gap: 0` in the
        // style array neutralizes the class (style prop > className in
        // NativeWind precedence) so spacing never doubles up.
        style={[gap > 0 && { margin: -gap / 2, gap: 0 }, style]}
        {...props}
      >
        {items.map((child, i) => {
          const cellStyle = [
            { width: cellWidth, flexGrow: 0, flexShrink: 0 },
            gap > 0 && { padding: gap / 2 },
          ];
          return cascade ? (
            <SwitchOn
              key={i}
              role="cell"
              delay={cascadeDelay + rowDelay(i)}
              className={cn(cellClassName)}
              style={cellStyle}
            >
              {child}
            </SwitchOn>
          ) : (
            <View key={i} role="cell" className={cn(cellClassName)} style={cellStyle}>
              {child}
            </View>
          );
        })}
      </View>
    );
  }
);

Grid.displayName = "Grid";

TSX example.tsx

import { Grid } from "@/components/ui/grid/grid";

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

Installation

npx @lumioui/cli add grid

Copy the source from the Code tab into your project
components/ui/grid/grid.tsxcomponents/ui/grid/index.ts
Update the import paths to match your project setup.

Usage

import { Grid } from "@/components/ui/grid/grid";

<Grid />

Examples

Product grid

A two-column product grid in a clothing store: photo tile, name, price.

npx @lumioui/cli add grid-menu

TSX components/ui/grid/variants/menu.tsx

import * as React from "react";
import { View } from "react-native";
import { BAND_STAGGER, Sheen, SwitchOn } from "@lumioui/core";
import { Grid } from "../grid";
import { Icon } from "../../icon/icon";
import { Image } from "../../image/image";
import { ActionSwapText } from "../../action-swap/action-swap";
import { LikeButton } from "../../like-button/like-button";
import { Text } from "../../text/text";

const PRODUCTS = [
  { name: "Boxy linen overshirt", price: "$118", photo: "photo-1740711152088-88a009e877bb" },
  { name: "Colour-block trainer", price: "$145", photo: "photo-1560769629-975ec94e6a86" },
  { name: "Relaxed wool coat", price: "$290", photo: "photo-1619603364937-8d7af41ef206" },
  { name: "Everyday tee, 3-pack", price: "$64", photo: "photo-1489987707025-afc232f7ea0f" },
];

/** One product tile. Saving fills the heart in place and a single sheen
 *  crosses the photo — the saved thing is what lights up. */
function ProductTile({
  p,
  saved,
  onSavedChange,
}: {
  p: (typeof PRODUCTS)[number];
  saved: boolean;
  onSavedChange: (saved: boolean) => void;
}) {
  const [sheen, setSheen] = React.useState(0);
  return (
    <View className="gap-2">
      <View className="overflow-hidden rounded-xl">
        <Image
          source={{ uri: `https://images.unsplash.com/${p.photo}?w=400&h=500&fit=crop&q=70&auto=format` }}
          aspectRatio={4 / 5}
          rounded="xl"
          className="w-full bg-muted"
          alt={p.name}
        />
        <Sheen run={sheen} />
        <View className="absolute right-1 top-1">
          <LikeButton
            variant="overlay"
            size="sm"
            color="destructive"
            hideCount
            liked={saved}
            onLikedChange={(next) => {
              if (next) setSheen((n) => n + 1);
              onSavedChange(next);
            }}
            accessibilityLabel={saved ? `Remove ${p.name} from saved` : `Save ${p.name}`}
          />
        </View>
      </View>
      <View>
        <Text className="text-[15px] font-medium" numberOfLines={1}>{p.name}</Text>
        <Text className="text-[15px] tabular-nums text-muted-foreground">{p.price}</Text>
      </View>
    </View>
  );
}

/** GridMenu — a two-column product grid in a clothing store: photo tile,
 *  name, price. Tiles switch on in reading order under the header. The
 *  heart on each tile fills in place and the header count swaps with a
 *  short rise or fall. Ink on neutral, the fashion-retail idiom. Built
 *  from free parts only (like-button, action-swap). */
export function GridMenu() {
  const [saved, setSaved] = React.useState<string[]>(["Relaxed wool coat"]);
  const set = (name: string, on: boolean) =>
    setSaved((s) => (on ? (s.includes(name) ? s : [...s, name]) : s.filter((x) => x !== name)));
  return (
    <View className="w-full gap-3">
      <SwitchOn className="flex-row items-end justify-between px-1">
        <View>
          <Text className="text-2xl font-bold tracking-tight">New this week</Text>
          <Text variant="muted">Northbound Supply · 48 items</Text>
        </View>
        <View className="flex-row items-center gap-1 pb-1">
          <Icon name="heart" size="sm" color="foreground" filled={saved.length > 0} />
          <ActionSwapText value={String(saved.length)}>
            <Text className="text-[15px] font-medium tabular-nums text-foreground">{saved.length}</Text>
          </ActionSwapText>
        </View>
      </SwitchOn>
      <Grid columns={2} gap={12} cascade cascadeDelay={BAND_STAGGER} className="w-full">
        {PRODUCTS.map((p) => (
          <ProductTile
            key={p.name}
            p={p}
            saved={saved.includes(p.name)}
            onSavedChange={(on) => set(p.name, on)}
          />
        ))}
      </Grid>
    </View>
  );
}

API reference

Prop Type Default

columns number

Number of columns. Default 2.

2

gap number

Gap between cells in px.

0

className string —

cellClassName string

Extra classes for each cell wrapper.

—

cascade boolean

Cells switch on in reading order at mount (dim → on, 40ms apart). Default false.

false

cascadeDelay number

Wait before the first cell switches on, in ms — to follow a header band. Default 0.

0

children React.ReactNode —

Primitives

Composed

Screens

Grid

Preview

Installation

Usage

Examples

Categories

Product grid

API reference

Preview

Installation

Usage

Examples

Categories

Product grid

API reference

Related