API Reference

This section provides comprehensive API documentation for all VitalGrid components, hooks, and utilities.

Core Functions

createVitalGrid

The main factory function for creating VitalGrid instances.

import { createVitalGrid } from '@fed/vital-grid';

const VitalGrid = createVitalGrid(config);

Parameters

config: VitalGridConfig - Configuration object for the grid instance

Returns

VitalGridResult - Object containing the hook, provider, and components

Example

const VitalGrid = createVitalGrid({
  features: {
    sorting: true,
    filtering: true,
    columnResizing: true,
    virtualization: true,
  },
  fields: {
    text: createTextField({ maxLength: 100 }),
    number: createNumberField({ min: 0, max: 100 }),
  },
});

Configuration Types

VitalGridConfig

Prop

Type

Configuration object for createVitalGrid.

FeatureConfig

Feature flags for table functionality.

interface FeatureConfig {
  sorting?: boolean;
  filtering?: boolean;
  columnReordering?: boolean;
  rowReordering?: boolean;
  columnResizing?: boolean;
  virtualization?: boolean;
  views?: boolean;
  selection?: boolean;
  addColumn?: boolean;
}

Properties

sorting?: boolean - Enable column sorting
filtering?: boolean - Enable row filtering
columnReordering?: boolean - Enable column drag & drop
rowReordering?: boolean - Enable row drag & drop
columnResizing?: boolean - Enable column resizing
virtualization?: boolean - Enable virtual scrolling
views?: boolean - Enable view management
selection?: boolean - Enable row selection
addColumn?: boolean - Enable add column button

Hook

useVitalGrid

Main hook for creating table instances with data.

const { grid, VitalGridProvider } = VitalGrid.useVitalGrid(options);

Parameters

options: UseVitalGridOptions - Options for table configuration

Returns

UseVitalGridResultWithCompound - Object containing grid state and provider

Example

function MyTable() {
  const { grid } = VitalGrid.useVitalGrid({
    data: tableData,
    columns: tableColumns,
    dataSource: myDataSource,
  });

  return (
    <VitalGridProvider grid={grid} workspaceId="my-table" height={600}>
      {/* Components */}
    </VitalGridProvider>
  );
}

UseVitalGridOptions

Prop

Type

Options for useVitalGrid hook.

Components

VitalGridProvider

Context provider for grid instances.

<VitalGridProvider
  grid={grid}
  workspaceId="my-table"
  height={600}
>
  {/* Grid components */}
</VitalGridProvider>

Props

grid: object - Grid object from useVitalGrid
workspaceId?: string - Unique identifier for the workspace
viewId?: string - Unique identifier for the view
height?: number - Height of the table
estimateRowHeight?: number - Estimated row height for virtualization
className?: string - Additional CSS classes

VitalGridRoot

Root container component for the grid.

<VitalGridRoot className="custom-grid">
  {/* Grid content */}
</VitalGridRoot>

Props

children: React.ReactNode - Child components
className?: string - Additional CSS classes
Extends HTMLAttributes<HTMLDivElement>

VitalGridToolbar

Toolbar component with optional controls.

<VitalGridToolbar showViewControls={true}>
  <VitalGridToolbar.Slot name="left">
    <Button onClick={refresh}>Refresh</Button>
  </VitalGridToolbar.Slot>
  <VitalGridToolbar.Slot name="right">
    <Button onClick={export}>Export</Button>
  </VitalGridToolbar.Slot>
</VitalGridToolbar>

Props

showViewControls?: boolean - Show view management controls
children?: React.ReactNode - Child components

VitalGridHeader

Header component with sortable columns.

<VitalGridHeader className="custom-header" />

Props

className?: string - Additional CSS classes
Extends HTMLAttributes<HTMLDivElement>

VitalGridBody

Body component with virtualized rows.

<VitalGridBody className="custom-body" />

Props

className?: string - Additional CSS classes
Extends HTMLAttributes<HTMLDivElement>

Data Source Interface

VitalGridDataSource

Prop

Type

Interface for connecting VitalGrid to any backend.

VitalGridColumn

Column definition used by VitalGrid.

interface VitalGridColumn {
  id: string;
  header: string;
  type: string;
  settings?: Record<string, unknown>;
  width?: number;
  order?: number;
  pinned?: 'left' | 'right';
}

Utilities

createColumnDef

Converts VitalGridColumn to TanStack Table ColumnDef.

const columnDef = VitalGrid.createColumnDef({
  id: 'name',
  header: 'Name',
  type: 'text',
  width: 200,
});

generateMetaId

Generates unique IDs for columns and other metadata.

const id = generateMetaId(); // "meta_abc123def"

generateRowId

Generates unique IDs for rows.

const id = generateRowId(); // "row_xyz789abc"

Field Types

Text Field

Basic text input field.

const textField = createTextField({
  maxLength: 100,
  multiline: false,
  placeholder: 'Enter text',
});

Number Field

Numeric input field with validation.

const numberField = createNumberField({
  min: 0,
  max: 100,
  precision: 2,
  step: 0.1,
});

Status Field

Dropdown field with colored badges.

const statusField = createStatusField({
  options: [
    { id: 'active', label: 'Active', color: '#10b981' },
    { id: 'inactive', label: 'Inactive', color: '#6b7280' },
  ],
  multi: false,
});

Date Field

Date picker field.

const dateField = createDateField({
  showTime: true,
  format: 'MM/DD/YYYY',
  minDate: new Date(),
});

Boolean Field

Toggle or checkbox field.

const booleanField = createBooleanField({
  showToggle: true,
  trueLabel: 'Enabled',
  falseLabel: 'Disabled',
});

Type Definitions

GenericRowData

Base interface for row data.

interface GenericRowData {
  [key: string]: any;
}

ViewConfig

Configuration for saved views.

interface ViewConfig {
  id: string;
  name: string;
  description?: string;
  columnOverrides: Array<{
    columnId: string;
    order: number;
    hidden: boolean;
    width?: number;
  }>;
  sort: Array<{ by: string; dir: 'asc' | 'desc' }>;
  filters: Record<string, any>;
  metadata?: Record<string, any>;
}

API Reference

On this page