GridSheet Props

The GridSheet component accepts the following props to configure its behavior and appearance.

Props Overview

Initial Cells

The initialCells prop defines the starting data and configuration for your spreadsheet. This is where you specify cell values, styles, renderers, policies, and other cell-specific settings.

Important: This is the initial value given to the sheet. Changes made after initialization will not be reflected, so please be careful.

Address Format

The format uses cell addresses as keys for cell configuration objects. For example, to set the text color of D3 to green, use {D3: {style: {color: "#00FF00"}}}.

Default Configuration

The default key applies configuration to all cells in the spreadsheet. This is useful for setting global defaults like width, height, or styles.

const initialCells = {
  default: { 
    width: 100, 
    height: 30,
    style: { fontSize: '14px' }
  },
  'A1': { value: 'Hello World' },
  'B2': { value: 100 },
};

Header Configuration

Header dimensions are configured using the 0 key for both header height and header width:

const initialCells = {
  // Header height and width (row 0)
  '0': {
    height: 60,  // Header height
    width: 80,   // Header width
  },
  // Other cells...
  'A1': { value: 'Hello World' },
};

Note: Header width is set on row 0, not on column letters. Column letters like 'A': { width: 80 } only affect the width of that specific column, not the header width.

Column and Row Specifications

For columns and rows, you can specify using only one side of the address:

• Columns: Use just the column letter (e.g., D for column D)
• Rows: Use just the row number (e.g., 3 for row 3)

Column/Row Specific Properties

Some properties are only valid for columns or rows:

Note: If you specify width or height on a cell address like D3, it will be ignored.

Cell Configuration

Each cell can be configured with the following properties:

Important Notes:

• Serialization: Cell values (except system field) are designed to be serializable. Avoid storing non-serializable objects like class instances.
• System Field: The system field contains values used by the system to display correct values. Do not modify this field manually.

Prevention Flags

The prevention property uses bitwise flags from the operations export to restrict specific operations on cells, columns, or rows. Multiple flags can be combined with the | (OR) operator.

import { operations } from '@gridsheet/react-core';

Convenience aliases:

// Prevent sorting and filtering on column C
{
  C: {
    prevention: operations.Sort | operations.Filter,
  },
}
 
// Column with a custom label, protected from label editing
{
  A: {
    label: 'Name',
    prevention: operations.SetLabel,
  },
}

Example Usage

const initialCells = {
  // Default configuration for all cells
  default: { 
    width: 100, 
    height: 30,
    style: { fontSize: '14px' }
  },
  
  // Header configuration
  '0': { 
    height: 60,  // Header height
    width: 80,   // Header width
  },
  
  // Individual cell configuration
  'A1': { value: 'Hello World', style: { color: '#FF0000' } },
  'B2': { value: 100, renderer: 'currency' },
  'C3': { value: 'Active', policy: 'status' },
  
  // Column configuration
  'A': { width: 150, labeler: 'custom' },
  'B': { width: 200 },
  
  // Row configuration
  '1': { height: 40 },
  '2': { height: 50, labeler: 'custom' },
};
 
<GridSheet initialCells={initialCells} />

Hub-Registered Components

The labeler, renderer, parser, and policy properties reference components that are registered in the hub by their string keys:

• Labeler: References a labeler function registered in hub.labelers
• Renderer: References a renderer instance registered in hub.renderers
• Parser: References a parser instance registered in hub.parsers
• Policy: References a policy instance registered in hub.policies

Example Usage

const hub = useHub({
  renderers: {
    currency: new Renderer({ mixins: [CurrencyRendererMixin] }),
    percentage: new Renderer({ mixins: [PercentageRendererMixin] }),
  },
  policies: {
    status: new Policy({ mixins: [StatusPolicyMixin] }),
  },
  labelers: {
    custom: (n: number) => `Row ${n}`,
  },
});
 
// In initialCells configuration
{
  'A1': {
    value: 1000,
    renderer: 'currency',  // References hub.renderers.currency
    style: { backgroundColor: '#f0f9ff' },
  },
  'B1': {
    value: 'Active',
    policy: 'status',      // References hub.policies.status
  },
  'C1': {
    labeler: 'custom',     // References hub.labelers.custom
  },
}

Note: The system property is managed internally by GridSheet and should not be specified manually.

Sheet Name

A unique identifier for the sheet that enables cross-sheet references and communication. When multiple sheets share a hub, the sheet name is used to distinguish between them for formula calculations and data sharing.

Hub

The hub enables communication between multiple GridSheet instances. Use the useHub hook to create a shared hub that allows sheets to reference each other's data in formulas.

Hub Configuration

The useHub hook accepts configuration options that are shared across all sheets using the same hub:

Event Handler Table Identification

When multiple sheets share the same hub, event handlers receive a table parameter that contains the UserTable instance. You can use table.sheetName to identify which sheet triggered the event:

const hub = useHub({
  onChange: ({ table, points }) => {
    if (table.sheetName === 'Sales') {
      console.log('Sales sheet data changed:', points);
    } else if (table.sheetName === 'Inventory') {
      console.log('Inventory sheet data changed:', points);
    }
  },
  onRemoveRows: ({ table, ys }) => {
    console.log(`Rows removed from ${table.sheetName}:`, ys);
  },
  onInsertCols: ({ table, x, numCols }) => {
    console.log(`Inserted ${numCols} columns at position ${x} in ${table.sheetName}`);
  },
  onKeyUp: ({ e, points }) => {
    console.log(`Key pressed: ${e.key} at position:`, points);
  },
  onInit: ({ table }) => {
    console.log(`Table initialized: ${table.sheetName}`);
  },
});

Important: Always use table.sheetName for conditional logic when multiple sheets share the same hub to ensure proper event handling and data management.