Atom Grid Table

A highly customizable React table component built with CSS Grid and Subgrid, offering cell-level control and modern layout capabilities.

Documentation: https://agt.sanbira.com/

Features

• 🎯 Built for React applications
• 📐 CSS Grid-based layout with Subgrid support
• 🎨 Customizable down to individual cell level
• 🔄 Built-in sorting functionality
• 📄 Pagination support
• ✨ Row selection capabilities
• 📱 Resizable columns
• 🔍 Loading state with skeleton placeholders
• 🎭 Multiple theme support
• 🎪 Zebra striping option
• 📊 Header row configuration
• 📌 Sticky header and sticky row support
• 🚀 Virtualization support for large datasets
• ⚡ Lightweight with minimal dependencies (only React and React DOM)

Dependencies

The package has minimal dependencies:

• react (^18.2.0)
• react-dom (^18.2.0)
• react-use (^17.5.1)

Installation

npm install @sanbira/atom-grid-table

Usage

import { AtomGridTable } from "@sanbira/atom-grid-table";
import "@sanbira/atom-grid-table/style.css";
import type { TableProps, TableRow, TableCell, ColOption } from "@sanbira/atom-grid-table";

const colOptions: ColOption[] = [
  { label: "Name", name: "name", width: "200px" },
  { label: "Age", name: "age", width: "100px" },
];

const rows: TableRow[] = [
  {
    cells: [{ content: "John Doe" }, { content: "30" }],
  },
  {
    cells: [{ content: "Jane Smith" }, { content: "25" }],
  },
];

function MyTable() {
  return <AtomGridTable colOptions={colOptions} rows={rows} isHasSelect={true} tableTheme="basic" />;
}

Props

TableProps

interface TableProps {
  colOptions: ColOption[];
  rows: TableRow[];
  className?: string;
  isLoading?: boolean;
  selectedRows?: string[];
  isHasSelect?: boolean;
  tableTheme?: string;
  selectionArea?: string;
  isPagination?: boolean;
  isVirtualization?: boolean;
  setSelected?: (selected: string[]) => void;
  paginationOptions?: PaginationOptions;
  sortingOptions?: Partial<SortingOptions>;
  virtualizationOptions?: VirtualizationOptions;
  tableStyleOptions?: TableStyleOptions;
  onPageOptionChange?: (pageOptions: PaginationChangeOptions) => void;
  onSortOptionChange?: (sortOptions: SortingChangeOptions) => void;
  onChange?: (generalOptions: { pageOptions: PaginationChangeOptions; sortOptions: SortingChangeOptions }) => void;
}

ColOption

interface ColOption {
  label?: string;
  tooltip?: string;
  name?: string;
  width?: string;
  isResizable?: boolean;
  resizeOptions?: { min: number; max: number };
  isHeadersColumn?: boolean;
}

TableRow

interface TableRow {
  cells: (TableCell | undefined)[];
  isActive?: boolean;
  selectIdentifier?: string;
  isHeader?: boolean;
  isSticky?: boolean;
}

TableCell

interface TableCell {
  content: ReactNode;
  span?: number;
  isOneLine?: boolean;
  isNumber?: boolean;
  isHeader?: boolean;
  isNoPadding?: boolean;
  isDisabled?: boolean;
  isCentered?: boolean;
}

TableStyleOptions

interface TableStyleOptions {
  isFirstRowHeader?: boolean;
  isZebra?: boolean;
  isNoXCellBorders?: boolean;
  isSmallCellPadding?: boolean;
  isStickyHeader?: boolean;
  loaderRowsCount?: number;
  colorScheme?: "light" | "dark";
}

VirtualizationOptions

interface VirtualizationOptions {
  rowHeight?: number;
  isStickyHeader?: boolean;
  tableHeight?: string | number;
}

Virtualization

Atom Grid Table supports virtualization for efficiently rendering large datasets. Enable it using the isVirtualization prop:

<AtomGridTable
  colOptions={colOptions}
  rows={largeDataset}
  isVirtualization={true}
  virtualizationOptions={{
    rowHeight: 48, // Height of each row in pixels
    isStickyHeader: true, // Whether the header should stick to the top
    tableHeight: "80dvh", // Height of the table container (px or CSS value)
  }}
/>

Virtualization only renders the rows currently visible in the viewport, significantly improving performance for tables with many rows.

Custom Components

Atom Grid Table allows you to replace its base components with your own custom implementations. This is done through the AtomGridTableProvider context. Here's how to use it:

import { AtomGridTableProvider } from "@sanbira/atom-grid-table";

// Your custom components
const CustomTooltip = (props) => <div className="my-tooltip">{props.children}</div>;
const CustomSelect = (props) => <select className="my-select">{props.children}</select>;
const CustomIconButton = (props) => <button className="my-icon-button">{props.children}</button>;
const CustomTypography = (props) => <span className="my-typography">{props.children}</span>;
const CustomSkeleton = () => <div className="my-skeleton" />;
const CustomCheckbox = (props) => <input type="checkbox" className="my-checkbox" {...props} />;

function App() {
  return (
    <AtomGridTableProvider
      customComponents={{
        tooltip: CustomTooltip,
        select: CustomSelect,
        iconButton: CustomIconButton,
        typography: CustomTypography,
        skeleton: CustomSkeleton,
        checkbox: CustomCheckbox,
      }}
    >
      <AtomGridTable colOptions={colOptions} rows={rows} />
    </AtomGridTableProvider>
  );
}

Available Custom Components

You can replace any of these base components:

• tooltip: For tooltip functionality
• select: For dropdown selections
• iconButton: For icon buttons
• typography: For text elements
• skeleton: For loading states
• checkbox: For checkbox inputs

Table Context Provider

The AtomGridTableProvider allows you to set default options and custom components that will be used across all AtomGridTable instances within its scope. This is particularly useful for:

1. Setting global table defaults
2. Providing custom components
3. Maintaining consistent styling and behavior across multiple tables

Usage

import { AtomGridTableProvider } from "@sanbira/atom-grid-table";

function App() {
  return (
    <AtomGridTableProvider
      defaultTableOptions={{
        tableStyleOptions: {
          isFirstRowHeader: true,
          isZebra: true,
          isNoXCellBorders: false,
          isSmallCellPadding: true,
        },
        isHasSelect: true,
        loaderRowsCount: 5,
        // ... other default options
      }}
      customComponents={
        {
          // ... your custom components
        }
      }
    >
      <AtomGridTable colOptions={colOptions} rows={rows} />
      <AtomGridTable colOptions={otherColOptions} rows={otherRows} />
    </AtomGridTableProvider>
  );
}

Props

interface AtomGridTableContextProps {
  defaultTableOptions?: Partial<TableProps>;
  customComponents?: {
    tooltip?: React.ComponentType<TooltipProps>;
    select?: React.ComponentType<SelectProps>;
    iconButton?: React.ComponentType<IconButtonProps>;
    typography?: React.ComponentType<TypographyProps>;
    skeleton?: React.ComponentType;
    checkbox?: React.ComponentType<CheckboxProps>;
  };
}

License

MIT