Column Fields

Graphite Grid uses the field property to determine the value of a cell for a given row. The grid will use the column's id property if the field property is not provided.

Field Calculators

The value of the field property can be:

A number, representing an index of an array. This can also be a property value.
A string, representing the property of a data object.
A function, which will return a field value.

Regardless of the field type used, a cell's value works best if the returned value is a simple primitive type. By default, the Grid does not know how to render object or Array values and will require custom cell renderers to support these types.

Field is a `number`

Graphite Grid expects individual row data items to be arrays when the field property is a number, though this is not a hard requirement. A number field allows for more compact row data representations than string properties and is the fastest way to compute the field for a column.

const rowData = [
  ["Rob Co", 1884, 3002],
  ["Cats R Us", 1993, 112],
  ["Carl Inc", 2024, 1],
];
 
export function HeaderFieldNumber() {
  const grid = useGraphiteGrid({
    initial: {
      columnDefinitions: [
        { id: "company-name", headerLabel: "Company Name", field: 0 },
        { id: "founded", headerLabel: "Founded", field: 1 },
        { id: "employee-count", headerLabel: "No. Employee", field: 2 },
      ],
      rowDataSource: {
        kind: "client",
        data: rowData,
      },
      // other grid properties
    },
  });
 
  return (
    <div style={{ height: 200 }}>
      <GraphiteGridDom state={grid} />
    </div>
  );
}

Field is a `string`

When the field property is a string, Graphite Grid treats the string as a path to a property. Generally, the data provided to the grid is an array of objects without nesting, though nested object values are supported.

A field can be a property like companyName or a path to a nested property, like nested.alpha[0]. A string like nested.alpha[0] tells the grid to access the property nested, then the property alpha, and finally retrieve the item at index 0. The grid will handle undefined chains, so if any part of the chain is not defined, the grid will not throw.

const rowDataString = [
  {
    companyName: "Rob Co",
    founded: 1884,
    employeeCount: 3002,
    nested: { alpha: [1] },
  },
  {
    companyName: "Cats R Us",
    founded: 1993,
    employeeCount: 112,
    nested: { alpha: [2] },
  },
  {
    companyName: "Carl Inc",
    founded: 2024,
    employeeCount: 1,
    nested: { alpha: [3] },
  },
];
 
export function HeaderFieldString() {
  const grid = useGraphiteGrid({
    initial: {
      columnDefinitions: [
        {
          id: "companyName",
          headerLabel: "Company Name",
          field: "companyName",
        },
        { id: "founded", headerLabel: "Founded", field: "founded" },
        {
          id: "employeeCount",
          headerLabel: "No. Employee",
          field: "employeeCount",
        },
        { id: "alphaKey", headerLabel: "Alpha Key", field: "nested.alpha[0]" },
      ],
      rowDataSource: {
        kind: "client",
        data: rowDataString,
      },
      // other grid properties
    },
  });
 
  return (
    <div style={{ height: 200 }}>
      <GraphiteGridDom state={grid} />
    </div>
  );
}

Field is a `function`

When the field is a function, Graphite Grid will evaluate the function to get the cell's value. If possible, avoid using functions to calculate field values as they are more expensive to compute. Functions are mostly useful for creating values that depend on more than a single field in a data object.

const rowDataFunction = [
  { id: "Alpha", values: [123, 344, 224, 455, 212] },
  { id: "Beta", values: [123, 455, 212, 114] },
  { id: "Gamma", values: [123, 344, 224, 455, 212, 22] },
];
 
export function HeaderFieldFunction() {
  const grid = useGraphiteGrid({
    initial: {
      columnDefinitions: [
        { id: "Greek", field: ({ data }) => data.id },
        { id: "Sum", field: ({ data }) => data.values.reduce((a, b) => a + b) },
        { id: "Count", field: ({ data }) => data.values.length },
      ],
      rowDataSource: {
        kind: "client",
        data: rowDataFunction,
      },
      // other grid properties
    },
  });
 
  return (
    <div style={{ height: 200 }}>
      <GraphiteGridDom state={grid} />
    </div>
  );
}

Field Formatter

The fieldFormatter property allows a field value to be further formatted for display purposes only. The function that receives the computed field value and should return a string.

In the example below, the employee-count field is formatted such that if the value is 1, an Employee suffix is added, but if it is not 1, then Employees is added instead.

export function HeaderFieldFormatter() {
  const grid = useGraphiteGrid({
    initial: {
      columnDefinitions: [
        { id: "company-name", headerLabel: "Company Name", field: 0 },
        { id: "founded", headerLabel: "Founded", field: 1 },
        {
          id: "employee-count",
          headerLabel: "No. Employee",
          field: 2,
          fieldFormatter: ({ field }) => {
            if (field === 1) return `${field} Employee`;
            return `${field as string} Employees`;
          },
        },
      ],
      // other grid properties
    },
  });
 
  return (
    <div style={{ height: 200 }}>
      <GraphiteGridDom state={grid} />
    </div>
  );
}

Performance Consideration

The columns in Graphite Grid allow for complex expressions for cell values. The Grid was designed to display thousands of cells, so the calculation of fields needs to be done as fast as possible. Deeply nested string property paths or expensive function fields can degrade grid performance.