ia-table

A powerful, feature-rich React data table component for enterprise applications.

Installation

npm install --save ia-table

Development Setup

If you're contributing to this project or have cloned the repository, follow these steps:

1. Install Dependencies

npm install

2. ESLint Configuration

This project uses ESLint 9+ with Flat Config format. The configuration is in eslint.config.js.

Running ESLint

# Check for linting errors
npm run lint

# Auto-fix linting errors
npm run lint:fix

IDE Integration

VS Code:

1. Install the ESLint extension
2. Install the Prettier extension
3. Create .vscode/settings.json in the project root with:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[javascriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ]
}

This configuration enables:

• Auto-format on save with Prettier
• Auto-fix ESLint errors on save
• Consistent formatting across all file types

Other IDEs:

• Most modern IDEs support ESLint flat config format
• Ensure your IDE's ESLint plugin is updated to the latest version

What's Configured

• React Hooks Rules: Enforces React hooks best practices
• React Refresh: Warns about components that can't be hot-reloaded
• React Compiler: Optimizations for React 19+
• TypeScript Support: Full TypeScript linting with typescript-eslint
• Ignored Paths: Automatically ignores dist/, build/, node_modules/, config files, and example files

Customizing Rules

To modify linting rules, edit eslint.config.js:

{
  rules: {
    "your-rule": "error", // or "warn" or "off"
  }
}

3. Prettier Configuration

This project uses Prettier for consistent code formatting across the team.

Running Prettier

# Format all files
npm run format

# Check if files are formatted (useful for CI)
npm run format:check

IDE Integration

The .vscode/settings.json configuration shown in the ESLint section above already includes Prettier integration. No additional setup needed if you've already configured VS Code for ESLint.

Other IDEs:

• Most modern IDEs have Prettier plugins available
• Configuration is automatically detected from .prettierrc

ESLint + Prettier Integration

The project is configured so that:

• ESLint handles code quality rules (bugs, best practices)
• Prettier handles code formatting (spacing, line breaks, quotes)
• eslint-config-prettier disables conflicting ESLint formatting rules

4. Available Scripts

# Development server
npm start

# Build library for production
npm run build:lib

# Run tests
npm test

# Linting
npm run lint          # Check for linting errors
npm run lint:fix      # Auto-fix linting errors

# Formatting
npm run format        # Format all files with Prettier
npm run format:check  # Check if files are formatted

# Storybook for component development
npm run storybook

# Build Storybook
npm run build:storybook

Quick Start

import IATable from "ia-table";

const App = () => {
  const data = [
    { id: 1, name: "Product A", price: 100 },
    { id: 2, name: "Product B", price: 200 },
  ];

  const columns = [
    { field: "id", headerName: "ID" },
    { field: "name", headerName: "Name" },
    { field: "price", headerName: "Price" },
  ];

  return (
    <IATable data={data} columns={columns} height="400px" uniqueIdField="id" />
  );
};

Features

Core Table Features

• Data Display:

  • Renders tabular data with fully customizable columns
  • Supports complex data objects and nested properties
  • Handles large datasets efficiently with virtualization
  • Displays empty state and loading indicators

• Responsive Layout:

  • Adapts to container size with proper overflow handling
  • Horizontal scrolling for tables wider than their container
  • Maintains header alignment with body cells during scroll
  • Supports fixed height or auto-expanding layouts

• Dynamic Column Configuration:

  • Configure width, alignment, sorting, filtering, and resizing per column
  • Support for complex column hierarchies with nested column groups
  • Custom cell renderers for advanced content formatting
  • Header customization with custom renderers
  • Column freezing/pinning for better navigation of wide tables
  • Show/hide columns via the column toggle menu

Data Management

• Sorting:

  • Sort data by any column in ascending or descending order
  • Visual indicators for sort direction
  • Support for custom sort functions
  • Multi-column sorting capability
  • Maintains sort state between renders

• Pagination:

  • Built-in pagination with customizable page size
  • Page navigation controls (previous, next, first, last)
  • Dynamic calculation of total pages
  • Efficient page switching without re-rendering the entire table
  • Customizable page size options

• Filtering:

  • Global search functionality across all columns or specific columns
  • Column-specific filtering with custom filter inputs
  • Advanced filter panel with multiple filter conditions
  • Filter operators include: contains, equals, startsWith, endsWith, etc.
  • Support for numeric filters (greater than, less than)
  • Date filtering capabilities
  • Boolean filters (is/is not)
  • Empty/not empty filters

Row Features

• Row Selection:

  • Single or multi-row selection with checkbox support
  • Select all/deselect all functionality
  • Selection persistence between page changes
  • Selection state callbacks for external state management
  • Visual indication of selected rows
  • Access to selection data through context

• Row Expansion:

  • Expandable rows with custom content
  • Expand/collapse indicators with animation
  • Customizable expanded content renderer
  • Independent expansion state for each row
  • Context-aware expansion tracking

• Row Grouping:

  • Support for hierarchical data with parent-child relationships
  • Configurable grouping fields
  • Visual indicators for grouped data
  • Expand/collapse functionality for group items
  • Custom renderers for group rows
  • Supports multiple levels of nesting

• Row Virtualization:

  • Performance optimization for large datasets (>100 rows)
  • Only renders visible rows and a small buffer
  • Seamless scrolling through thousands of rows
  • Dynamic height calculation for varying row heights
  • Memory efficient for very large datasets
  • Maintains scroll position during updates

UI Components

• Table Header:

  • Customizable with sort indicators
  • Support for multi-level column groups
  • Column resizing via drag handles
  • Fixed positioning during scroll
  • Context menu for column operations
  • Support for custom header cell renderers

• Table Body:

  • Efficient rendering with virtualization for large datasets
  • Custom cell renderers for complex content
  • Row and cell event handlers (click, hover, etc.)
  • Support for keyboard navigation
  • Proper handling of null/undefined values
  • Type-aware cell formatting

• Table Footer:

  • Optional with pagination controls
  • Summary row capabilities
  • Aggregate function support (sum, average, count, etc.)
  • Fixed positioning for easy access
  • Custom footer renderers

• Toolbar:

  • Search functionality with debounced input
  • Column visibility toggle
  • Export options (CSV, Excel, etc.)
  • Custom action buttons
  • Responsive design for mobile compatibility

• Column Toggle Menu:

  • Show/hide columns dynamically
  • Drag and drop column reordering
  • Reset to default option
  • Search columns functionality
  • Column group management

• Filter Panel:

  • Complex filtering interface
  • Add/remove filter conditions
  • Combine multiple filters
  • Filter operator selection
  • Type-aware filter inputs
  • Save filter presets

Visual Customization

• Column Resizing:

  • Drag handles to adjust column widths
  • Visual feedback during resize operation
  • Minimum/maximum width constraints
  • Double-click to auto-size based on content
  • Persist column width preferences

• Styling:

  • Comprehensive CSS for enterprise appearance
  • Support for theming and custom styles
  • Responsive design principles
  • Accessible color schemes
  • Row alternating colors
  • Hover and selection styles

• Custom Cell Rendering:

  • Format cell content with custom renderers
  • Support for complex components within cells
  • Cell editor integration
  • Conditional formatting based on cell values
  • Support for images, icons, and rich content

Performance Optimizations

• Virtualized Rendering:

  • Only renders visible rows for large datasets
  • Significantly improves performance for tables with thousands of rows
  • Dynamic buffer size calculation
  • Smooth scrolling experience
  • Efficient DOM reuse

• Memoization:

  • Efficient re-rendering using React.useMemo
  • Prevents unnecessary calculations during renders
  • Smart component updates based on changed props
  • Optimized context usage to prevent re-renders

• Optimized Filtering:

  • Smart filter application for large datasets
  • Debounced search input to prevent excessive filtering
  • Cached filter results when possible
  • Progressive filtering for complex conditions
  • Background processing for non-blocking UX

Usage

import IATable from "ia-table";

// Sample data
const data = [
  { id: 1, name: "Product A", category: "Electronics", price: 299.99 },
  { id: 2, name: "Product B", category: "Furniture", price: 599.99 },
  // ...more rows
];

// Column definitions
const columns = [
  {
    field: "id",
    headerName: "ID",
    width: 80,
    sortable: true,
  },
  {
    field: "name",
    headerName: "Product Name",
    width: 200,
    sortable: true,
    filterable: true,
  },
  {
    field: "category",
    headerName: "Category",
    width: 150,
    sortable: true,
    filterable: true,
  },
  {
    field: "price",
    headerName: "Price",
    width: 120,
    align: "right",
    sortable: true,
    filterable: true,
    cellRenderer: ({ value }) => `$${value.toFixed(2)}`,
  },
];

// Component implementation
const MyTable = () => {
  return (
    <IATable
      data={data}
      columns={columns}
      height="500px"
      uniqueIdField="id"
      selectable={true}
      pagination={true}
      pageSize={10}
    />
  );
};

Props

| Prop | Type | Default | Description | | ----------------- | ------- | --------------- | -------------------------------------------------- | | data | Array | [] | Array of data objects to display | | columns | Array | [] | Column definitions | | height | String | 'auto' | Table height | | uniqueIdField | String | 'store_code' | Field to use as unique row identifier | | childKeyField | String | 'status_obj1' | Field containing child items for hierarchical data | | showHeader | Boolean | true | Whether to show the table header | | showFooter | Boolean | false | Whether to show the table footer | | showToolbar | Boolean | true | Whether to show the toolbar | | selectable | Boolean | false | Enable row selection | | expandable | Boolean | false | Enable row expansion | | pagination | Boolean | false | Enable pagination | | defaultPageSize | Number | 10 | Items per page when pagination is enabled |

Column Definition

interface ColumnDefinition {
  field: string; // The field name in the data object
  headerName: string; // The display name for the column header
  width?: number; // The width of the column in pixels (default: 100)
  isSortable?: boolean; // Whether the column is sortable (default: true)
  filterable?: boolean; // Whether the column is filterable (default: true)
  resizable?: boolean; // Whether the column can be resized (default: true)
  cellRenderer?: Function; // Custom cell renderer function
  align?: "left" | "center" | "right"; // Text alignment (default: 'left')
  pinned?: boolean | "left"; // Whether the column is pinned (true = right, 'left' = left)
  is_hidden?: boolean; // Whether the column is initially hidden
}