Headless Component Parts

LyteNyte Grid is a headless data grid. Each part of the grid is split into constituent components that you can compose declaratively to form the grid view.

All grid components live on the Grid export from the LyteNyte Grid packages.

1
import { Grid } from "@1771technologies/lytenyte-core";

1
import { Grid } from "@1771technologies/lytenyte-pro";

The Grid export is the root component of LyteNyte Grid. The Grid component has two modes depending on whether you pass children:

• Default Mode: Enabled when the children prop is undefined. In this mode, the Grid component renders the headless structure that LyteNyte Grid needs to function in the default setup. This is the recommended mode unless you need to attach custom logic to the individual component parts of the grid.
• Headless Mode: Enabled when you pass children to the Grid component. In this mode, you must render each grid component part to create a valid view. The component parts are defined on the Grid component itself. For example, you can render the header using Grid.Header.

The remainder of this guide walks through the individual grid components and then shows a complete demo example. This guide is best read from top to bottom. For a complete working example, see the Getting Started guide.

Grid Anatomy Overview

The code below offers a high-level overview of the individual parts of the grid component anatomy. Treat this example as a general outline of the grid structure.

Apart from the LyteNyte grid’s default mode, Headless Mode has two variants:

• Headless Mode: A variant that only renders the top-level containers.
• Full Headless Mode: A fully rendered variant that renders every cell.

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header />
4
    <Grid.RowsContainer>
5
      <Grid.RowsTop />
6
      <Grid.RowsCenter />
7
      <Grid.RowsBottom />
8
    </Grid.RowsContainer>
9
  </Grid.Viewport>
10
</Grid>

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header>
4
      {(cells) => {
5
        return (
6
          <Grid.HeaderRow>
7
            {cells.map((c) => {
8
              if (c.kind === "group") return <Grid.HeaderGroupCell cell={c} key={c.idOccurrence} />;
9

10
              return <Grid.HeaderCell cell={c} key={c.id} />;
11
            })}
12
          </Grid.HeaderRow>
13
        );
14
      }}
15
    </Grid.Header>
16
    <Grid.RowsContainer>
17
      <Grid.RowsTop>
18
        {(row) => {
19
          if (row.kind === "full-width") return <Grid.RowFullWidth row={row} />;
20

21
          return (
22
            <Grid.Row key={row.id} row={row}>
23
              {row.cells.map((cell) => {
24
                return <Grid.Cell cell={cell} key={cell.id} />;
25
              })}
26
            </Grid.Row>
27
          );
28
        }}
29
      </Grid.RowsTop>
30
      <Grid.RowsCenter>
31
        {(row) => {
32
          if (row.kind === "full-width") return <Grid.RowFullWidth row={row} />;
33

34
          return (
35
            <Grid.Row key={row.id} row={row}>
36
              {row.cells.map((cell) => {
37
                return <Grid.Cell cell={cell} key={cell.id} />;
38
              })}
39
            </Grid.Row>
40
          );
41
        }}
42
      </Grid.RowsCenter>
43
      <Grid.RowsBottom>
44
        {(row) => {
45
          if (row.kind === "full-width") return <Grid.RowFullWidth row={row} />;
46

47
          return (
48
            <Grid.Row key={row.id} row={row}>
49
              {row.cells.map((cell) => {
50
                return <Grid.Cell cell={cell} key={cell.id} />;
51
              })}
52
            </Grid.Row>
53
          );
54
        }}
55
      </Grid.RowsBottom>
56
    </Grid.RowsContainer>
57
  </Grid.Viewport>
58
</Grid>

1
<Grid />

Grid

The Grid component acts as the root component for all grid elements. It accepts grid props as state and provides its children with the necessary context for LyteNyte Grid to function. The Grid component also exposes the other component parts as properties.

1
<Grid>{/* Other component parts here. */}</Grid>

Viewport

The Grid.Viewport component creates the element that acts as the overflow parent for the grid. As its name suggests, it defines the visible area of the grid and displays rows and columns based on the scroll position. The viewport automatically sizes to fit its container. See the Responsive Container guide for details on configuring containers for the grid.

Adding Grid.Viewport to the grid component gives us:

1
<Grid>
2
  <Grid.Viewport />
3
</Grid>

Grid.Viewport renders a div element. It accepts all standard div props, including className and style. LyteNyte Grid also applies inline styles for grid sizing.

Header

LyteNyte Grid has a single header container, rendered by the Grid.Header component. You can render the Grid.Header component in two ways:

• Without children: The header component uses the default configuration to render header groups and header cells.
• With children: The header component accepts a render prop as its children, which gives you an opportunity to add customizations before rendering the header group and header cell elements.

Rendering Grid.Header without children is the most straightforward approach. The Grid.Header component renders a normal div element and accepts all standard div props.

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header />
4
  </Grid.Viewport>
5
</Grid>

Header Render Prop

Passing a render prop as the children of the Grid.Header component allows for more fine-grained control over how the header renders. When using this approach, the render prop must return a Grid.HeaderRow, and that component must render the header cells as its children.

The render prop function receives an array of LayoutHeader items. Each LayoutHeader item describes the layout of an individual header cell, such as whether the cell is pinned or whether the cell belongs to a column group, a normal header, or a floating header.

You can use this information to apply custom logic, though the default rendering behavior is usually the best place to start.

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header>
4
      {(cells) => {
5
        return <Grid.HeaderRow>{/* Header row content */}</Grid.HeaderRow>;
6
      }}
7
    </Grid.Header>
8
  </Grid.Viewport>
9
</Grid>

Header Row

When using a custom render prop for Grid.Header, the function must return a Grid.HeaderRow element. The total number of header rows equals the maximum column group depth, plus one additional row for the floating row (if enabled), and another row for the column header row.

The Grid.Header component renders a normal div element and accepts all standard div props. The Grid.Header render prop receives an array of header cells as its first argument. You must use these header cells to render the children of the Grid.HeaderRow, as shown in the example below.

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header>
4
      {(cells) => {
5
        return (
6
          <Grid.HeaderRow>
7
            {cells.map((c) => {
8
              // Return cell content.
9
            })}
10
          </Grid.HeaderRow>
11
        );
12
      }}
13
    </Grid.Header>
14
  </Grid.Viewport>
15
</Grid>

Header Cells

Within each <Grid.HeaderRow />, you render header cells. These cells represent column headers. LyteNyte Grid provides two header cell components:

• Grid.HeaderGroupCell: Renders the cell for a column group.
• Grid.HeaderCell: Renders the cell for a column header or a floating header cell.

The render prop of Grid.Header receives an array of cells to render. Each item in this array represents a single header cell. You must render these cells inside a Grid.HeaderRow element, as shown below.

You can determine which component to render by checking the cell’s kind property. When the cell’s kind is "group", render a Grid.HeaderGroupCell. Otherwise, render a Grid.HeaderCell.

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header>
4
      {(cells) => {
5
        return (
6
          <Grid.HeaderRow>
7
            {cells.map((c) => {
8
              if (c.kind === "group") return <Grid.HeaderGroupCell cell={c} key={c.idOccurrence} />;
9

10
              return <Grid.HeaderCell cell={c} key={c.id} />;
11
            })}
12
          </Grid.HeaderRow>
13
        );
14
      }}
15
    </Grid.Header>
16
  </Grid.Viewport>
17
</Grid>

There are several details to note here. For each cell, choose the appropriate header component base on the kind property. For Grid.HeaderGroupCell, use c.idOccurrence as the key instead of c.id. A column group can be split across the header, so c.id may repeat. React requires keys to be unique within a list, and c.idOccurrence guarantees uniqueness.

Rows Container

Use the Grid.RowsContainer component to render the grid’s rows. Grid.RowsContainer is similar to Grid.Header in that it:

• Acts as the container for the grid rows.
• Renders a normal div element and accepts all standard div props.

An updated example is shown below:

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header />
4
    <Grid.RowsContainer />
5
  </Grid.Viewport>
6
</Grid>

Top, Center, and Bottom Rows

Grid.RowsContainer is the parent for all grid rows. LyteNyte Grid splits rows into three component sections:

• Grid.RowsTop: Rows that are pinned to the top of the viewport, after the header.
• Grid.RowsCenter: Scrollable rows that render after the top rows.
• Grid.RowsBottom: Rows that are pinned to the bottom of the viewport.

Each section component accepts an optional render prop as children, giving you more fine-grained control over how rows and cells render. Like Grid.Header, this approach provides two ways to render rows:

• Without a Render Prop: Default mode and the simplest approach that renders the row section without a render prop
• With a Render Prop: Provide a render prop as children to a row section component to gain more control over row rendering.

The code snippet below demonstrates the default mode structure, so it’s equivalent to rendering <Grid />.

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header />
4
    <Grid.RowsContainer>
5
      <Grid.RowsTop />
6
      <Grid.RowsCenter />
7
      <Grid.RowsBottom />
8
    </Grid.RowsContainer>
9
  </Grid.Viewport>
10
</Grid>

Rows Render Prop

The render prop receives a LayoutRow item. Each LayoutRow describes the type of row to render, along with properties such as rowIndex and rowPin. You can use these values to apply row-specific logic.

There are two types of grid row components:

• Grid.RowFullWidth: Renders a row with a single cell that spans the width of the viewport.
• Grid.Row: Renders a row that must be provided an array of Grid.Cell elements as children. Each Grid.Cell element renders a single cell in the viewport.

Use the LayoutRow passed to the render prop to determine which row type to render, as shown below.

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header />
4
    <Grid.RowsContainer>
5
      <Grid.RowsTop />
6
      <Grid.RowsCenter>
7
        {(row) => {
8
          if (row.kind === "full-width") return <Grid.RowFullWidth row={row} />;
9

10
          return (
11
            <Grid.Row key={row.id} row={row}>
12
              {/* Cell content here */}
13
            </Grid.Row>
14
          );
15
        }}
16
      </Grid.RowsCenter>
17
      <Grid.RowsBottom />
18
    </Grid.RowsContainer>
19
  </Grid.Viewport>
20
</Grid>

Row Cells

All rows contain cells except for full-width rows. The cells property on LayoutRow is an array of cells that you render using Grid.Cell. Updating the row section component results in the following:

1
<Grid>
2
  <Grid.Viewport>
3
    <Grid.Header />
4
    <Grid.RowsContainer>
5
      <Grid.RowsTop />
6
      <Grid.RowsCenter>
7
        {(row) => {
8
          if (row.kind === "full-width") return <Grid.RowFullWidth row={row} />;
9

10
          return (
11
            <Grid.Row key={row.id} row={row}>
12
              {row.cells.map((cell) => {
13
                return <Grid.Cell cell={cell} key={cell.id} />;
14
              })}
15
            </Grid.Row>
16
          );
17
        }}
18
      </Grid.RowsCenter>
19
      <Grid.RowsBottom />
20
    </Grid.RowsContainer>
21
  </Grid.Viewport>
22
</Grid>

The cells must be rendered as children of a Grid.Row component. Each Grid.Cell renders a div element and accepts all standard div props.

Putting It All Together

Everything so far has focused on assembling the grid. The example below shows a full working setup that combines all the parts covered in the previous sections. The demo includes rows pinned to the top and bottom, column groups, and the full row structure.

4 collapsed lines
1
import "@1771technologies/lytenyte-pro/light-dark.css";
2
import { Grid, useClientDataSource } from "@1771technologies/lytenyte-pro";
3
import { bankDataSmall } from "@1771technologies/grid-sample-data/bank-data-smaller";
4
import { ViewportShadows } from "@1771technologies/lytenyte-pro/components";
5

6
type BankData = (typeof bankDataSmall)[number];
7
export interface GridSpec {
8
  readonly data: BankData;
9
}
10

11
const [under30, under50, over50] = Object.values(
12
  Object.groupBy(
13
    bankDataSmall.toSorted((l, r) => l.age - r.age),
14
    (r) => {
15
      if (r.age < 30) return "Under 30";
16
      if (r.age < 50) return "Under 50";
17
      return "Over 50";
18
    },
19
  ),
20
);
21

22
const finalData = [
23
  { id: "full-width", label: "Under 30 Years Old" } as unknown as BankData,
24
  ...under30,
25
  { id: "full-width", label: "Between 30 and 49 Years Old" } as unknown as BankData,
26
  ...under50,
27
  { id: "full-width", label: "Over 50 Years Old" } as unknown as BankData,
28
  ...over50,
29
];
30

31
const columns: Grid.Column<GridSpec>[] = [
32
  { name: "Job", id: "job", width: 120 },
33
  { name: "Age", id: "age", type: "number", width: 80, cellRenderer: NumberCell },
34
  { name: "Balance", id: "balance", groupPath: ["Background"], type: "number", cellRenderer: BalanceCell },
35
  { name: "Education", id: "education", groupPath: ["Background"] },
36
  { name: "Marital", id: "marital" },
37
  { name: "Default", id: "default" },
38
  { name: "Housing", id: "housing" },
39
  { name: "Loan", id: "loan" },
40
  { name: "Contact", id: "contact" },
41
  { name: "Day", id: "day", type: "number", cellRenderer: NumberCell },
42
  { name: "Month", id: "month" },
43
  { name: "Duration", id: "duration", type: "number", cellRenderer: DurationCell },
44
];
45

46
const base = { width: 100 };
47

48
const rowFullWidthPredicate: Grid.Props<GridSpec>["rowFullWidthPredicate"] = (r) =>
49
  Boolean(r.row.data && "id" in r.row.data && r.row.data.id === "full-width");
50
const rowFullWidthRenderer: Grid.Props<GridSpec>["rowFullWidthRenderer"] = (r) => {
51
  const data = r.row.data as { label: string };
52

53
  return (
54
    <div className="text-ln-gray-70 border-ln-gray-20 flex h-full w-full items-center justify-center border-y font-bold">
55
      {data.label}
56
    </div>
57
  );
58
};
59

60
export default function GridDemo() {
61
  const ds = useClientDataSource({
62
    data: finalData,
63
    topData: bankDataSmall.slice(0, 2),
64
    botData: bankDataSmall.slice(2, 4),
65
  });
66

67
  return (
68
    <div className="ln-grid ln-header-group:justify-center" style={{ height: 500 }}>
69
      <Grid
70
        rowSource={ds}
71
        rowFullWidthPredicate={rowFullWidthPredicate}
72
        rowFullWidthRenderer={rowFullWidthRenderer}
73
        columns={columns}
74
        columnBase={base}
75
        slotShadows={ViewportShadows}
76
      >
77
        <Grid.Viewport>
78
          <Grid.Header />
79
          <Grid.RowsContainer>
80
            <Grid.RowsTop />
81
            <Grid.RowsCenter />
82
            <Grid.RowsBottom />
83
          </Grid.RowsContainer>
84
        </Grid.Viewport>
85
      </Grid>
86
    </div>
87
  );
88
}
89

26 collapsed lines
90
const formatter = new Intl.NumberFormat("en-US", {
91
  maximumFractionDigits: 2,
92
  minimumFractionDigits: 0,
93
});
94
export function BalanceCell({ api, row, column }: Grid.T.CellRendererParams<GridSpec>) {
95
  const field = api.columnField(column, row);
96

97
  if (typeof field === "number") {
98
    if (field < 0) return `-$${formatter.format(Math.abs(field))}`;
99

100
    return "$" + formatter.format(field);
101
  }
102

103
  return `${field ?? "-"}`;
104
}
105
export function DurationCell({ api, row, column }: Grid.T.CellRendererParams<GridSpec>) {
106
  const field = api.columnField(column, row);
107

108
  return typeof field === "number" ? `${formatter.format(field)} days` : `${field ?? "-"}`;
109
}
110

111
export function NumberCell({ api, row, column }: Grid.T.CellRendererParams<GridSpec>) {
112
  const field = api.columnField(column, row);
113

114
  return typeof field === "number" ? formatter.format(field) : `${field ?? "-"}`;
115
}

Next Steps

• Responsive Container: Learn how to configure containers for LyteNyte Grid.
• API Extensions: Extend LyteNyte Grid's base API with custom functions and state.
• Grid Reactivity: Learn how LyteNyte Grid enables declarative reactivity.