Support custom tagName for outer element and (optional) children

Author: bvaughn

lib/components/grid/Grid.test.tsx

@@ -159,6 +159,48 @@ describe("Grid", () => {
     // TODO
   });
 
+  test("custom tagName and attributes", () => {
+    function CustomCellComponent({ style }: CellComponentProps<object>) {
+      return <span style={style}>Cell</span>;
+    }
+
+    const { container } = render(
+      <Grid
+        cellComponent={CustomCellComponent}
+        cellProps={EMPTY_OBJECT}
+        columnCount={100}
+        columnWidth={25}
+        overscanCount={0}
+        rowCount={100}
+        rowHeight={20}
+        tagName="main"
+      />
+    );
+
+    expect(container.firstElementChild?.tagName).toBe("MAIN");
+    expect(container.querySelectorAll("SPAN")).toHaveLength(8);
+  });
+
+  test("children", () => {
+    const { container } = render(
+      <Grid
+        cellComponent={CellComponent}
+        cellProps={EMPTY_OBJECT}
+        columnCount={100}
+        columnWidth={25}
+        overscanCount={0}
+        rowCount={100}
+        rowHeight={20}
+      >
+        <div id="custom">Overlay or tooltip</div>
+      </Grid>
+    );
+
+    expect(container.querySelector("#custom")).toHaveTextContent(
+      "Overlay or tooltip"
+    );
+  });
+
   describe("imperative API", () => {
     test.skip("should return the root element", () => {
       // TODO

lib/components/grid/Grid.tsx

@@ -1,4 +1,5 @@
 import {
+  createElement,
   memo,
   useEffect,
   useImperativeHandle,
@@ -9,13 +10,17 @@ import {
 import { useIsRtl } from "../../core/useIsRtl";
 import { useVirtualizer } from "../../core/useVirtualizer";
 import { useMemoizedObject } from "../../hooks/useMemoizedObject";
-import type { Align } from "../../types";
+import type { Align, TagNames } from "../../types";
 import { arePropsEqual } from "../../utils/arePropsEqual";
 import type { GridProps } from "./types";
 
-export function Grid<CellProps extends object>({
+export function Grid<
+  CellProps extends object,
+  TagName extends TagNames = "div"
+>({
   cellComponent: CellComponentProp,
   cellProps: cellPropsUnstable,
+  children,
   className,
   columnCount,
   columnWidth,
@@ -29,8 +34,9 @@ export function Grid<CellProps extends object>({
   rowCount,
   rowHeight,
   style,
+  tagName = "div" as TagName,
   ...rest
-}: GridProps<CellProps>) {
+}: GridProps<CellProps, TagName>) {
   const cellProps = useMemoizedObject(cellPropsUnstable);
   const CellComponent = useMemo(
     () => memo(CellComponentProp, arePropsEqual),
@@ -247,16 +253,28 @@ export function Grid<CellProps extends object>({
     rowStopIndex
   ]);
 
-  return (
+  const sizingElement = (
     <div
-      aria-colcount={columnCount}
-      aria-rowcount={rowCount}
-      role="grid"
-      {...rest}
-      className={className}
-      dir={dir}
-      ref={setElement}
+      aria-hidden
       style={{
+        height: getEstimatedHeight(),
+        width: getEstimatedWidth(),
+        zIndex: -1
+      }}
+    ></div>
+  );
+
+  return createElement(
+    tagName,
+    {
+      "aria-colcount": columnCount,
+      "aria-rowcount": rowCount,
+      role: "grid",
+      ...rest,
+      className,
+      dir,
+      ref: setElement,
+      style: {
         position: "relative",
         width: "100%",
         height: "100%",
@@ -265,18 +283,10 @@ export function Grid<CellProps extends object>({
         flexGrow: 1,
         overflow: "auto",
         ...style
-      }}
-    >
-      {cells}
-
-      <div
-        aria-hidden
-        style={{
-          height: getEstimatedHeight(),
-          width: getEstimatedWidth(),
-          zIndex: -1
-        }}
-      ></div>
-    </div>
+      }
+    },
+    cells,
+    children,
+    sizingElement
   );
 }

lib/components/grid/types.ts

@@ -5,21 +5,17 @@ import type {
   ReactNode,
   Ref
 } from "react";
+import type { TagNames } from "../../types";
 
 type ForbiddenKeys = "columnIndex" | "rowIndex" | "style";
 type ExcludeForbiddenKeys<Type> = {
   [Key in keyof Type]: Key extends ForbiddenKeys ? never : Type[Key];
 };
 
-export type GridProps<CellProps extends object> = Omit<
-  HTMLAttributes<HTMLDivElement>,
-  "onResize"
-> & {
-  /**
-   * CSS class name.
-   */
-  className?: string;
-
+export type GridProps<
+  CellProps extends object,
+  TagName extends TagNames = "div"
+> = Omit<HTMLAttributes<HTMLDivElement>, "onResize"> & {
   /**
    * React component responsible for rendering a cell.
    *
@@ -48,6 +44,17 @@ export type GridProps<CellProps extends object> = Omit<
    */
   cellProps: ExcludeForbiddenKeys<CellProps>;
 
+  /**
+   * Additional content to be rendered within the grid (above cells).
+   * This property can be used to render things like overlays or tooltips.
+   */
+  children?: ReactNode;
+
+  /**
+   * CSS class name.
+   */
+  className?: string;
+
   /**
    * Number of columns to be rendered in the grid.
    */
@@ -137,6 +144,14 @@ export type GridProps<CellProps extends object> = Omit<
    * The grid of cells will fill the height and width defined by this style.
    */
   style?: CSSProperties;
+
+  /**
+   * Can be used to override the root HTML element rendered by the List component.
+   * The default value is "div", meaning that List renders an HTMLDivElement as its root.
+   *
+   * ⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.
+   */
+  tagName?: TagName;
 };
 
 export type CellComponent<CellProps extends object> =

lib/components/list/List.test.tsx

@@ -329,6 +329,44 @@ describe("List", () => {
     expect(screen.queryByTestId("foo")).toHaveRole("list");
   });
 
+  test("custom tagName and attributes", () => {
+    function CustomRowComponent({ index, style }: RowComponentProps<object>) {
+      return <li style={style}>Row {index + 1}</li>;
+    }
+
+    const { container } = render(
+      <List
+        overscanCount={0}
+        rowCount={4}
+        rowComponent={CustomRowComponent}
+        rowHeight={25}
+        rowProps={EMPTY_OBJECT}
+        tagName="ul"
+      />
+    );
+
+    expect(container.firstElementChild?.tagName).toBe("UL");
+    expect(container.querySelectorAll("LI")).toHaveLength(4);
+  });
+
+  test("children", () => {
+    const { container } = render(
+      <List
+        overscanCount={0}
+        rowCount={100}
+        rowComponent={RowComponent}
+        rowHeight={25}
+        rowProps={EMPTY_OBJECT}
+      >
+        <div id="custom">Overlay or tooltip</div>
+      </List>
+    );
+
+    expect(container.querySelector("#custom")).toHaveTextContent(
+      "Overlay or tooltip"
+    );
+  });
+
   describe("imperative API", () => {
     test("should return the root element", () => {
       const listRef = createRef<ListImperativeAPI>();

lib/components/list/List.tsx

@@ -1,4 +1,5 @@
 import {
+  createElement,
   memo,
   useEffect,
   useImperativeHandle,
@@ -8,11 +9,15 @@ import {
 } from "react";
 import { useVirtualizer } from "../../core/useVirtualizer";
 import { useMemoizedObject } from "../../hooks/useMemoizedObject";
-import type { Align } from "../../types";
+import type { Align, TagNames } from "../../types";
 import { arePropsEqual } from "../../utils/arePropsEqual";
 import type { ListProps } from "./types";
 
-export function List<RowProps extends object>({
+export function List<
+  RowProps extends object,
+  TagName extends TagNames = "div"
+>({
+  children,
   className,
   defaultHeight = 0,
   listRef,
@@ -23,9 +28,10 @@ export function List<RowProps extends object>({
   rowCount,
   rowHeight,
   rowProps: rowPropsUnstable,
+  tagName = "div" as TagName,
   style,
   ...rest
-}: ListProps<RowProps>) {
+}: ListProps<RowProps, TagName>) {
   const rowProps = useMemoizedObject(rowPropsUnstable);
   const RowComponent = useMemo(
     () => memo(RowComponentProp, arePropsEqual),
@@ -123,30 +129,34 @@ export function List<RowProps extends object>({
     return children;
   }, [RowComponent, getCellBounds, rowCount, rowProps, startIndex, stopIndex]);
 
-  return (
+  const sizingElement = (
     <div
-      role="list"
-      {...rest}
-      className={className}
-      ref={setElement}
+      aria-hidden
       style={{
+        height: getEstimatedSize(),
+        width: "100%",
+        zIndex: -1
+      }}
+    ></div>
+  );
+
+  return createElement(
+    tagName,
+    {
+      role: "list",
+      ...rest,
+      className,
+      ref: setElement,
+      style: {
         position: "relative",
         maxHeight: "100%",
         flexGrow: 1,
         overflowY: "auto",
         ...style
-      }}
-    >
-      {rows}
-
-      <div
-        aria-hidden
-        style={{
-          height: getEstimatedSize(),
-          width: "100%",
-          zIndex: -1
-        }}
-      ></div>
-    </div>
+      }
+    },
+    rows,
+    children,
+    sizingElement
   );
 }

lib/components/list/types.ts

@@ -5,16 +5,23 @@ import type {
   ReactNode,
   Ref
 } from "react";
+import type { TagNames } from "../../types";
 
 type ForbiddenKeys = "ariaAttributes" | "index" | "style";
 type ExcludeForbiddenKeys<Type> = {
   [Key in keyof Type]: Key extends ForbiddenKeys ? never : Type[Key];
 };
 
-export type ListProps<RowProps extends object> = Omit<
-  HTMLAttributes<HTMLDivElement>,
-  "onResize"
-> & {
+export type ListProps<
+  RowProps extends object,
+  TagName extends TagNames = "div"
+> = Omit<HTMLAttributes<HTMLDivElement>, "onResize"> & {
+  /**
+   * Additional content to be rendered within the list (above cells).
+   * This property can be used to render things like overlays or tooltips.
+   */
+  children?: ReactNode;
+
   /**
    * CSS class name.
    */
@@ -101,6 +108,14 @@ export type ListProps<RowProps extends object> = Omit<
    * The list of rows will fill the height defined by this style.
    */
   style?: CSSProperties;
+
+  /**
+   * Can be used to override the root HTML element rendered by the List component.
+   * The default value is "div", meaning that List renders an HTMLDivElement as its root.
+   *
+   * ⚠️ In most use cases the default ARIA roles are sufficient and this prop is not needed.
+   */
+  tagName?: TagName;
 };
 
 export type RowComponent<RowProps extends object> =

lib/types.ts

@@ -1 +1,4 @@
+import type { JSX } from "react";
 export type Align = "auto" | "center" | "end" | "smart" | "start";
+
+export type TagNames = keyof JSX.IntrinsicElements;

package.json

@@ -67,6 +67,7 @@
     "@types/react-dom": "^19.1.6",
     "@vitejs/plugin-react-swc": "^3.10.2",
     "clsx": "^2.1.1",
+    "csstype": "^3.1.3",
     "eslint": "^9.30.1",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.20",