Column Spanning

With LyteNyte Grid, cells can span multiple columns. When a cell spans, it extends into adjacent columns, and the grid skips rendering any cells it covers.

The colSpan property on a column definition controls how many columns a cell spans. It accepts either a number or a function.

Provide a number to apply the same span to all rows; or
Provide a function that returns a number to vary the span per row

Cells always span toward the end of the viewport. A spanning cell covers the next column, not the previous one.

Uniform Column Spans

When colSpan is a number, every cell in the column spans the same number of adjacent columns for all rows. The grid skips rendering any cells covered by the span. The demo below shows the USD Price column spanning over the adjacent GBP Price column.

Uniform Column Span

"use client";

import { Grid, useClientRowDataSource } from "@1771technologies/lytenyte-pro";
import "@1771technologies/lytenyte-pro/grid.css";
import type { Column } from "@1771technologies/lytenyte-pro/types";
import { stockData } from "@1771technologies/grid-sample-data/stock-data-smaller";
import { useId } from "react";
import {
  PercentCell,
  CurrencyCell,
  SymbolCell,
  CompactNumberCell,
  HeaderRenderer,
  AnalystRatingCell,
  PriceCell,
} from "./components";

type StockData = (typeof stockData)[number];

const columns: Column<StockData>[] = [
  { field: 0, id: "symbol", name: "Symbol", cellRenderer: SymbolCell, width: 220 },
  { field: 2, id: "analyst-rating", cellRenderer: AnalystRatingCell, width: 130 },
  {
    field: 3,
    id: "price",
    name: "USD Price",
    type: "number",
    cellRenderer: PriceCell,
    width: 110,
    colSpan: 2,
  },
  { id: "price", name: "GBP Price", type: "number", width: 110 },
  { field: 5, id: "change", type: "number", cellRenderer: PercentCell, width: 130 },
  { field: 11, id: "eps", name: "EPS", type: "number", cellRenderer: CurrencyCell, width: 130 },
  { field: 6, id: "volume", type: "number", cellRenderer: CompactNumberCell, width: 130 },
];

export default function ColumnFieldNumberIndex() {
  const ds = useClientRowDataSource({ data: stockData });

  const grid = Grid.useLyteNyte({
    gridId: useId(),
    rowDataSource: ds,
    columns,
    columnBase: {
      headerRenderer: HeaderRenderer,
      widthFlex: 1,
    },
  });

  const view = grid.view.useValue();

  return (
    <div className="lng-grid" style={{ height: 500 }}>
      <Grid.Root grid={grid}>
        <Grid.Viewport>
          <Grid.Header>
            {view.header.layout.map((row, i) => {
              return (
                <Grid.HeaderRow key={i} headerRowIndex={i}>
                  {row.map((c) => {
                    if (c.kind === "group") return null;

                    return (
                      <Grid.HeaderCell
                        key={c.id}
                        cell={c}
                        className="flex h-full w-full items-center px-2 capitalize"
                      />
                    );
                  })}
                </Grid.HeaderRow>
              );
            })}
          </Grid.Header>
          <Grid.RowsContainer>
            <Grid.RowsCenter>
              {view.rows.center.map((row) => {
                if (row.kind === "full-width") return null;

                return (
                  <Grid.Row row={row} key={row.id}>
                    {row.cells.map((c) => {
                      return (
                        <Grid.Cell key={c.id} cell={c} className="text-xs! flex text-nowrap" />
                      );
                    })}
                  </Grid.Row>
                );
              })}
            </Grid.RowsCenter>
          </Grid.RowsContainer>
        </Grid.Viewport>
      </Grid.Root>
    </div>
  );
}

import type { stockData } from "@1771technologies/grid-sample-data/stock-data-smaller";
import { memo, type ReactNode } from "react";
import { logos } from "@1771technologies/grid-sample-data/stock-data-smaller";
import type {
  CellRendererParams,
  HeaderCellRendererParams,
} from "@1771technologies/lytenyte-pro/types";
import type { ClassValue } from "clsx";
import clsx from "clsx";
import { twMerge } from "tailwind-merge";

type StockData = (typeof stockData)[number];

export function tw(...c: ClassValue[]) {
  return twMerge(clsx(...c));
}

function AnalystRatingCellImpl({ grid, row, column }: CellRendererParams<StockData>) {
  const field = grid.api.columnField(column, row) as string;

  let Icon: (() => ReactNode) | null = null;
  const label = field || "-";
  let clx = "";
  if (label === "Strong buy") {
    Icon = StrongBuy;
    clx = "text-green-500";
  } else if (label === "Strong Sell") {
    Icon = StrongSell;
    clx = "text-red-500";
  } else if (label === "Neutral") {
    Icon = Minus;
  } else if (label === "Buy") {
    Icon = Buy;
    clx = "text-green-500";
  } else if (label === "Sell") {
    Icon = Sell;
    clx = "text-red-500";
  }

  const aggModel = grid.state.aggModel.useValue();

  const activeAgg = aggModel[column.id];
  const isCount = activeAgg?.fn === "count";
  const isGroupRow = grid.api.rowIsGroup(row);

  return (
    <div
      className={tw(
        "grid h-full grid-cols-[16px_1fr] items-center gap-4 text-nowrap px-3",
        clx,
        isGroupRow && isCount && "flex justify-end",
      )}
    >
      {Icon && <Icon />}
      <div>
        {label}
        {isCount && <span className="pl-1">Ratings</span>}
      </div>
    </div>
  );
}

function Minus() {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      fill="none"
      viewBox="0 0 24 24"
      strokeWidth={1.5}
      stroke="currentColor"
      width={16}
    >
      <path strokeLinecap="round" strokeLinejoin="round" d="M5 12h14" />
    </svg>
  );
}

function Sell() {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      fill="none"
      viewBox="0 0 24 24"
      strokeWidth={1.5}
      stroke="currentColor"
      width={16}
    >
      <path strokeLinecap="round" strokeLinejoin="round" d="m19.5 8.25-7.5 7.5-7.5-7.5" />
    </svg>
  );
}

function Buy() {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      fill="none"
      viewBox="0 0 24 24"
      strokeWidth={1.5}
      stroke="currentColor"
      width={16}
    >
      <path strokeLinecap="round" strokeLinejoin="round" d="m4.5 15.75 7.5-7.5 7.5 7.5" />
    </svg>
  );
}

function StrongSell() {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      fill="none"
      viewBox="0 0 24 24"
      strokeWidth={1.5}
      stroke="currentColor"
      width={16}
    >
      <path
        strokeLinecap="round"
        strokeLinejoin="round"
        d="m4.5 5.25 7.5 7.5 7.5-7.5m-15 6 7.5 7.5 7.5-7.5"
      />
    </svg>
  );
}

function StrongBuy() {
  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      fill="none"
      viewBox="0 0 24 24"
      strokeWidth={1.5}
      stroke="currentColor"
      width={16}
    >
      <path strokeLinecap="round" strokeLinejoin="round" d="m4.5 18.75 7.5-7.5 7.5 7.5" />
      <path strokeLinecap="round" strokeLinejoin="round" d="m4.5 12.75 7.5-7.5 7.5 7.5" />
    </svg>
  );
}

export const AnalystRatingCell = memo(AnalystRatingCellImpl);

function CompactNumberCellImpl({ row, grid, column }: CellRendererParams<StockData>) {
  const field = grid.api.columnField(column, row);

  const isGroup = grid.api.rowIsGroup(row);
  const aggregations = grid.state.aggModel.useValue();
  const isCount = aggregations[column.id]?.fn === "count";

  const [label, suffix] =
    typeof field === "number"
      ? isGroup && isCount
        ? [Math.round(field), ""]
        : formatCompactNumber(field)
      : ["-", ""];

  return (
    <div className="flex h-full w-full items-center justify-end gap-1 text-nowrap px-3 tabular-nums">
      <span>{label}</span>
      <span className="font-semibold">{suffix}</span>
    </div>
  );
}

export const CompactNumberCell = memo(CompactNumberCellImpl);
function formatCompactNumber(n: number) {
  const suffixes = ["", "K", "M", "B", "T"];
  let magnitude = 0;
  let num = Math.abs(n);

  while (num >= 1000 && magnitude < suffixes.length - 1) {
    num /= 1000;
    magnitude++;
  }

  const decimals = 2;
  const formatted = num.toFixed(decimals);

  return [`${n < 0 ? "-" : ""}${formatted}`, suffixes[magnitude]];
}

const formatter = new Intl.NumberFormat("en-US", {
  minimumFractionDigits: 2,
  maximumFractionDigits: 2,
});

function CurrencyCellImpl({ grid, row, column }: CellRendererParams<StockData>) {
  const field = grid.api.columnField(column, row);

  const label = typeof field === "number" ? formatter.format(field) : "-";
  const currency = "USD";

  const aggregations = grid.state.aggModel.useValue();
  const isCount = aggregations[column.id]?.fn === "count";

  return (
    <div className="flex h-full w-full items-center justify-end text-nowrap px-3 tabular-nums">
      <div className="flex items-baseline gap-1">
        <span>{label}</span>
        {!isCount && <span className="text-[9px]">{currency}</span>}
      </div>
    </div>
  );
}

export const CurrencyCell = memo(CurrencyCellImpl);

function PriceCellImpl({ grid, row, column }: CellRendererParams<StockData>) {
  const field = grid.api.columnField(column, row);

  const label = typeof field === "number" ? formatter.format(field) : "-";
  const labelGBP = typeof field === "number" ? formatter.format(field * 1.36) : "-";

  const aggregations = grid.state.aggModel.useValue();
  const isCount = aggregations[column.id]?.fn === "count";

  return (
    <div className="flex h-full w-full items-center justify-end gap-1 text-nowrap px-3 tabular-nums">
      <div className="flex items-baseline gap-1">
        <span>{label}</span>
        {!isCount && <span className="text-[9px]">USD</span>}
      </div>
      <span>/</span>
      <div className="flex items-baseline gap-1">
        <span>{labelGBP}</span>
        {!isCount && <span className="text-[9px]">GBP</span>}
        @1.36
      </div>
    </div>
  );
}

export const PriceCell = memo(PriceCellImpl);

function CurrencyCellGBPImpl({ grid, row, column }: CellRendererParams<StockData>) {
  const field = grid.api.columnField(column, row);

  const label = typeof field === "number" ? formatter.format(field) : "-";
  const currency = "GBP";

  const aggregations = grid.state.aggModel.useValue();
  const isCount = aggregations[column.id]?.fn === "count";

  return (
    <div className="flex h-full w-full items-center justify-end text-nowrap px-3 tabular-nums">
      <div className="flex items-baseline gap-1">
        <span>{label}</span>
        {!isCount && <span className="text-[9px]">{currency}</span>}
      </div>
    </div>
  );
}

export const CurrencyCellGBP = memo(CurrencyCellGBPImpl);

function PercentCellImpl({ grid, row, column }: CellRendererParams<StockData>) {
  const field = grid.api.columnField(column, row) as number;

  const isGroup = grid.api.rowIsGroup(row);
  const aggregations = grid.state.aggModel.useValue();
  const isCount = aggregations[column.id]?.fn === "count";

  const label =
    typeof field === "number"
      ? isGroup && isCount
        ? Math.round(field)
        : formatter.format(field) + "%"
      : "-";

  return (
    <div
      className={tw("flex h-full w-full items-center justify-end text-nowrap px-3 tabular-nums")}
    >
      {label}
    </div>
  );
}

export const PercentCell = memo(PercentCellImpl);

function SymbolCellImpl({ grid, row, column }: CellRendererParams<StockData>) {
  if (grid.api.rowIsGroup(row)) {
    const data = row.data[column.id];

    const agg = grid.state.aggModel.get()[column.id];

    return (
      <div className="flex h-full items-center text-nowrap px-3">
        {data as string} {agg.fn === "count" ? (data === 1 ? "Symbol" : "Symbols") : ""}
      </div>
    );
  }
  if (!grid.api.rowIsLeaf(row)) return null;

  const symbol = grid.api.columnField(column, row) as string;
  const desc = row.data?.[1];

  return (
    <div className="grid h-full w-full grid-cols-[32px_1fr] items-center gap-3 overflow-hidden text-nowrap px-3">
      <div className="flex h-8 min-h-8 w-8 min-w-8 items-center justify-center overflow-hidden rounded-full">
        <img
          src={logos[symbol]}
          alt=""
          width={26}
          height={26}
          className="pointer-events-none h-[26px] min-h-[26px] w-[26px] min-w-[26] rounded-full bg-black p-1"
        />
      </div>
      <div className="overflow-hidden text-ellipsis">{desc}</div>
    </div>
  );
}
export const SymbolCell = memo(SymbolCellImpl);

export function HeaderRenderer({ column, grid }: HeaderCellRendererParams<StockData>) {
  const name = column.name ?? column.id;

  const isNumber = column.type === "number";

  const aggModel = grid.state.aggModel.useValue();
  const isGrouped = grid.state.rowGroupModel.useValue().length > 0;
  const agg = (aggModel[column.id]?.fn ?? "") as string;

  return (
    <div
      className={clsx(
        "text-ln-gray-80 group relative flex h-full w-full items-center gap-1 overflow-hidden text-nowrap px-2 text-xs",
        isNumber && "justify-end",
      )}
    >
      <span className={tw(isNumber && "order-2")}>{name}</span>
      {isGrouped && agg && (
        <div className={tw("text-ln-primary-50 text-xs", isNumber && "order-1")}>({agg})</div>
      )}
    </div>
  );
}

Uniform spans are uncommon and mainly appear in cases where the visual layout differs from the logical column structure. Hence, these types of column spans are used sparingly.

const columns = [
  // other columns,
  { field: 3, id: "price", type: "number", colSpan: 2 },
];

Function Column Spans

You can set colSpan to a function that returns the span for each row. This allows dynamic spans based on row data. The demo below merges cells for rows whose temperature values differ by less than 3.

Function Column Span

"use client";

import { Grid, useClientRowDataSource } from "@1771technologies/lytenyte-pro";
import "@1771technologies/lytenyte-pro/grid.css";
import type { CellSpanFnParams, Column } from "@1771technologies/lytenyte-pro/types";
import { useId } from "react";
import type { MonthlyTemperature } from "@1771technologies/grid-sample-data/temperatures";
import { data } from "@1771technologies/grid-sample-data/temperatures";
import { HeatMapCell, tw, YearCell } from "./components";

const ordering: (keyof MonthlyTemperature["temps"])[] = [
  "Jan",
  "Feb",
  "Mar",
  "Apr",
  "May",
  "Jun",
  "Jul",
  "Aug",
  "Sep",
  "Oct",
  "Nov",
  "Dec",
];

function joinSimilarTemps(x: CellSpanFnParams<MonthlyTemperature>) {
  if (x.row.kind !== "leaf" || !x.row.data) return 1;
  const temps = x.row.data.temps;
  const myOrder = ordering[x.colIndex - 1];
  const value = temps[myOrder];

  let count = 1;
  let i = x.colIndex; // index is already offset by 1 due to the year column
  while (true) {
    const next = ordering[i];

    if (!next) break;

    const nextValue = temps[next];
    if (myOrder === "Jul") console.log(next);
    if (Math.abs(nextValue - value) < 3) {
      count++;
      i++;
    } else {
      break;
    }
  }

  return count;
}

const columns: Column<MonthlyTemperature>[] = [
  { id: "year", cellRenderer: YearCell, width: 100 },
  { id: "Jan", colSpan: joinSimilarTemps },
  { id: "Feb", colSpan: joinSimilarTemps },
  { id: "Mar", colSpan: joinSimilarTemps },
  { id: "Apr", colSpan: joinSimilarTemps },
  { id: "May", colSpan: joinSimilarTemps },
  { id: "Jun", colSpan: joinSimilarTemps },
  { id: "Jul", colSpan: joinSimilarTemps },
  { id: "Aug", colSpan: joinSimilarTemps },
  { id: "Sep", colSpan: joinSimilarTemps },
  { id: "Oct", colSpan: joinSimilarTemps },
  { id: "Nov", colSpan: joinSimilarTemps },
  { id: "Dec", colSpan: joinSimilarTemps },
];

export default function ColumnBase() {
  const ds = useClientRowDataSource({ data: data });

  const grid = Grid.useLyteNyte({
    gridId: useId(),
    rowDataSource: ds,
    columns,

    columnBase: {
      widthMin: 30,
      width: 50,
      widthFlex: 1,
      cellRenderer: HeatMapCell,
    },
  });

  const view = grid.view.useValue();

  return (
    <div className="lng-grid" style={{ height: 500 }}>
      <Grid.Root grid={grid}>
        <Grid.Viewport>
          <Grid.Header>
            {view.header.layout.map((row, i) => {
              return (
                <Grid.HeaderRow key={i} headerRowIndex={i}>
                  {row.map((c) => {
                    if (c.kind === "group") return null;

                    return (
                      <Grid.HeaderCell
                        key={c.id}
                        cell={c}
                        className={tw(
                          "flex h-full w-full items-center justify-center text-nowrap text-sm capitalize",
                          c.column.type === "number" && "justify-end",
                        )}
                      />
                    );
                  })}
                </Grid.HeaderRow>
              );
            })}
          </Grid.Header>
          <Grid.RowsContainer>
            <Grid.RowsCenter>
              {view.rows.center.map((row) => {
                if (row.kind === "full-width") return null;

                return (
                  <Grid.Row row={row} key={row.id} className="group">
                    {row.cells.map((c) => {
                      return (
                        <Grid.Cell
                          key={c.id}
                          cell={c}
                          className="flex h-full w-full items-center justify-center text-sm"
                        />
                      );
                    })}
                  </Grid.Row>
                );
              })}
            </Grid.RowsCenter>
          </Grid.RowsContainer>
        </Grid.Viewport>
      </Grid.Root>
    </div>
  );
}

import type { MonthlyTemperature } from "@1771technologies/grid-sample-data/temperatures";
import type { CellRendererParams } from "@1771technologies/lytenyte-pro/types";
import type { ClassValue } from "clsx";
import clsx from "clsx";
import { twMerge } from "tailwind-merge";

export function tw(...c: ClassValue[]) {
  return twMerge(clsx(...c));
}

export function HeatMapCell({
  grid: { api },
  column,
  row,
}: CellRendererParams<MonthlyTemperature>) {
  if (!api.rowIsLeaf(row) || !row.data) return null;

  const value = row.data.temps[column.id as keyof MonthlyTemperature["temps"]];

  const bg = valueToColor(value);

  return (
    <div
      style={{ background: bg }}
      className="flex h-full w-full items-center justify-center text-white group-hover:opacity-70"
    >
      {value.toFixed(1)}°C
    </div>
  );
}

export function YearCell({ grid: { api }, row, column }: CellRendererParams<MonthlyTemperature>) {
  const field = api.columnField(column, row);

  return `${field}`;
}

/**
 * Interpolate between two HSL colors based on value in [0, 30].
 * 0  -> hsl(173.4 80.4% 40%)
 * 30 -> hsl(0 84.2% 60.2%)
 */
export function valueToColor(value: number): string {
  const percentage = Math.min((value / 19) * 100, 100);

  const start = "174.7 83.9% 31.6%";
  const end = "178.6 84.3% 10%";

  return `color-mix(in hsl, hsl(${start}) ${100 - percentage}%, hsl(${end}) ${percentage}%)`;
}

The colSpan function below shows how flexible span logic can be:

function joinSimilarTemps(x: CellSpanFnParams<MonthlyTemperature>) {
  if (x.row.kind !== "leaf" || !x.row.data) return 1;

  const temps = x.row.data.temps;
  const myOrder = ordering[x.colIndex - 1];
  const value = temps[myOrder];

  let count = 1;
  let i = x.colIndex; // Index is offset by 1 due to the year column

  while (true) {
    const next = ordering[i];
    if (!next) break;

    const nextValue = temps[next];
    if (Math.abs(nextValue - value) < 3) {
      count++;
      i++;
    } else {
      break;
    }
  }

  return count;
}

Column Span Scanning Distance

For performance, LyteNyte Grid does not pre-calculate all spans. Instead, it scans backward from the first visible column based on the scroll position. Control this lookback using the colScanDistance property:

const grid = Grid.useLyteNyte({
  // Other grid props
  colScanDistance: 100,
});

colScanDistance must be at least the maximum possible span in your grid. Ensure no span exceeds this value to guarantee correct rendering.

LyteNyte Grid uses a scan distance to ensure correctness and performance. Many grids pre-calculate spans, which limits scalability, or render incorrectly during scrolling. LyteNyte Grid's model requires you to specify a maximum span, but it maintains accuracy and performance.

In most real-world cases, a scan distance of 100 is more than enough, since spans rarely approach this size.

Next Steps

Column Base: See the default column values and how to override them.
Column Resizing: Change column widths programmatically or through user interaction.
Column ID & Name: Define user-friendly column names and ensure unique IDs.
Column Field: Control how a column retrieves each cell's value.