Renderers and editors

Overview

All of our custom cell rendering components are enabled by default in Grid Pro. These renderers provide flexible and extensible ways to customize cell content and interactions in grid columns. Grid Pro includes both cell renderers (for display) and cell editors (for data input).

Built-in Cell Renderers

Action renderer (action)

Renders a single action button within a grid cell, allowing for row-specific interactions.

Further details are available in the API documentation.

Key features

• The button name, appearance and style can be customized
• Supports disabled state based on row data
• Handles click events with optional async actions
• Supports E2E testing with data-test-id attributes

Usage example

const actionRendererColDef = {
  cellRenderer: 'action',
  cellRendererParams: {
    actionName: 'Edit',
    actionClick: (rowData) => handleEdit(rowData),
    isDisabled: (rowData) => !rowData.editable,
    appearance: 'primary',
    actionButtonStyle: 'color: #f5f5f5; font-weight: 700;',
  },
  // other column options
}

Actions menu renderer (actionsMenu)

Renders a menu of multiple actions for a grid row.

Further details are available in the API documentation.

Key features

• Supports multiple actions per row
• Customizable menu opener text and appearance
• Flexible action definition

Usage example

const actionsColDefs = getActionsMenuDef([
  {
    name: 'View',
    callback: (rowData) => viewDetails(rowData)
  },
  {
    name: 'Delete',
    callback: (rowData) => deleteRow(rowData)
  }
]);

const columnDefs = [
  { field: 'name' },
  // other defs
  actionsColDefs
];

const actionsMenuRendererColDef: ColDef = {
    cellRenderer: GridProRendererTypes.actionsMenu,
    cellRendererParams: {
      actions,
      buttonAppearance,
      isVertical,
      buttonText: customActionsOpenerName,
    },
    // other column options
  };

Boolean renderer (boolean)

Renders a checkbox within a grid cell, allowing direct boolean value editing.

Further details are available in the API documentation.

Key features

• Supports disabled state
• Automatically handles grid editing events
• Integrates with AG Grid's editing mechanism

Usage example

const booleanRendererColDef = {
  cellRenderer: 'boolean',
  cellRendererParams: {
    isDisabled: (rowData) => !rowData.canEdit
  },
  // other column options
}

Status pill renderer (statusPill)

Renders status values as colored pills or badges, providing visual status indicators.

Key features

• Customizable color schemes for different status values
• Supports value mapping and display labels
• Visual status indication with colored backgrounds
• Flexible configuration for different status types

Usage example

const statusPillRendererColDef = {
  headerName: 'Status',
  field: 'status',
  cellRenderer: 'statusPill',
  cellRendererParams: (params) => {
    // Checking a boolean flag
    if (params.value) {
      return {
        iconName: 'check',
        text: 'Enabled',
        backgroundColor: 'green',
      };
    } else {
      return {
        iconName: 'xmark',
        text: 'Disabled',
        backgroundColor: 'red',
      };
    }
  },
}

Text renderer (text)

Basic text display renderer with optional formatting capabilities.

Key features

• Simple text display
• Optional text formatting
• Lightweight rendering for basic text content
• Supports value formatters

Usage example

const textRendererColDef = {
  headerName: 'Description',
  field: 'description',
  cellRenderer: 'text',
  valueFormatter: (params) => params.value?.toUpperCase()
}

Text field renderer (textField)

Provides a text input field renderer for inline text editing.

Key features

• Inline text input capabilities
• Customizable placeholder text
• Supports validation and formatting
• Direct text editing within cells

Usage example

const textFieldRendererColDef = {
  headerName: 'Notes',
  field: 'notes',
  cellRenderer: 'textField',
  cellRendererParams: {
    placeholder: 'Add notes here...',
    maxLength: 200
  }
}

Select renderer (select)

Renders a dropdown select within a grid cell, allowing users to select from a list of options.

Further details are available in the API documentation.

Key features

• Supports dynamic options through a function
• Customizable option display names
• Supports disabled state per option
• Handles selection changes with callback
• Configurable dropdown position based on row index

Usage example

const ROW_INDEX_LIMIT = 5;

const setDropdownPosition = (rowData, allRows) => {
  const rowIndex = allRows.findIndex(row =>
    row.make === rowData.make &&
    row.model === rowData.model
  );
  return rowIndex > ROW_INDEX_LIMIT ? 'above' : 'below';
};

const selectRendererColDef = {
  headerName: 'Status',
  field: 'status',
  cellRenderer: 'select',
  cellStyle: {
    overflow: 'visible',
  },
  cellRendererParams: {
    options: () => [
      {
        name: 'available',
        displayName: 'Available',
        isDisabled: (rowData) => rowData.price > 50000,
        tooltip: 'This car is available',
      },
      {
        name: 'reserved',
        displayName: 'Reserved',
        isDisabled: (rowData) => rowData.year < 2020,
        tooltip: 'This car is not available',
      },
    ],
    onSelect: (rowData) => handleStatusChange(rowData),
    accessor: 'status',
    position: (rowData) => setDropdownPosition(rowData, allRows),
  }
}

Editable renderer (editable)

Renders a cell with a formatted value and an optional progress indicator.

Further details are available in the API documentation.

Key features

• Formats cell values
• Displays a progress ring for pending edits
• Lightweight and simple

Usage example

const editableRenderercolDef = {
  cellRenderer: 'editable',
  valueFormatter: (params) => formatCurrency(params.value),
  // other column options
}

Built-in Cell Editors

Select editor (selectEditor)

Renders a dropdown select editor within a grid cell, allowing users to edit cell values by selecting from a list of options.

Further details are available in the API documentation.

Key features

• Supports asynchronous data loading for options
• Customizable value and label fields
• Integrates with data sources
• Handles value changes and updates the grid data
• Supports both synchronous and asynchronous options

Usage example

const selectEditorRendererColDef = {
  cellEditor: 'selectEditor',
  cellEditorParams: {
    allOptionsResourceName: 'optionsResource',
    valueField: 'id',
    labelField: 'name',
    async: true,
    datasourceOptions: { /* datasource configuration */ },
    values: [/* static option values */],
  },
  // other column options
}

Number editor (numberEditor)

Provides a numeric input editor within a grid cell, allowing users to input and edit numerical values.

Further details are available in the API documentation.

Key features

• Supports number formatting options
• Customizable placeholder text
• Handles value changes and updates grid data
• Supports disabling the editor
• Built-in validation for numeric inputs
• Configurable precision and range limits

Usage example

const numberEditorRendererColDef = {
  cellEditor: 'numberEditor',
  cellEditorParams: {
    withFormatting: true,
    formatOptions: { style: 'currency', currency: 'USD' },
    placeholder: 'Enter amount',
    disabled: false,
    min: 0,
    max: 10000,
    precision: 2,
    step: 0.01
  },
  // other column options
}

Multiselect editor (multiselectEditor)

Provides a multi-select editor within a grid cell, allowing users to select multiple options.

Further details are available in the API documentation.

Key features

• Supports asynchronous data loading for options
• Customizable value and label fields
• Integrates with data sources
• Handles multiple selections
• Handles value changes and updates grid data

Usage example

const multiselectEditorRendererColDef = {
  cellEditor: 'multiselectEditor',
  cellEditorParams: {
    allOptionsResourceName: 'optionsResource', // Resource name for fetching options.
    valueField: 'id',
    labelField: 'name',
    async: true,
    datasourceOptions: { /* datasource configuration */ },
    values: [/* static option values */],
    selectedOptionsCallback: (data) => fetchSelectedOptions(data),
  },
  // other column options
}

Date editor (dateEditor)

Provides a date or date-time input editor within a grid cell, allowing users to input or edit date values.

Further details are available in the API documentation.

Key features

• Supports both date and date-time input types
• Customizable date format
• Handles value changes and updates grid data
• Automatically focuses on the editor when opened
• Built-in date validation
• Configurable date range restrictions

Usage example

const dateEditorRendererColDef = {
  cellEditor: 'dateEditor',
  cellEditorParams: {
    withTime: true, // Set to false for date only
    format: 'DD/MM/YYYY',
    placeholder: 'Select date',
    minDate: '2020-01-01',
    maxDate: '2030-12-31'
  },
  // other column options
}

String editor (stringEditor)

Provides a text input editor within a grid cell, allowing users to input or edit string values.

Further details are available in the API documentation.

Key features

• Customizable placeholder text
• Handles value changes and updates grid data
• Automatically focuses on the editor when opened
• Supports text validation
• Configurable maximum length

Usage example

const stringEditorRendererColDef = {
  cellEditor: 'stringEditor',
  cellEditorParams: {
    placeholder: 'Enter text',
    maxLength: 100,
    validator: (value) => value.length >= 3
  },
  // other column options
}

Automatic cell renderer selection

Grid Pro supports automatic cell renderer selection based on data types when using the auto-cell-renderer-by-type attribute:

<rapid-grid-pro auto-cell-renderer-by-type>
  <grid-pro-client-side-datasource resource-name="ALL_TRADES">
  </grid-pro-client-side-datasource>
</rapid-grid-pro>

This feature automatically selects appropriate renderers based on:

• Boolean values → Boolean renderer
• Date values → Date formatter
• Numeric values → Number formatter
• Status fields → Status pill renderer (when configured)

Creating a custom renderer component

To create a custom renderer component, you need to implement the ICellRendererComp interface from AG Grid. This interface defines the required methods for a renderer component.

Step-by-step implementation

1. Basic renderer structure

import {
  ICellRendererComp,
  ICellRendererParams
} from '@ag-grid-community/core';
import { GenesisElement, html, observable } from '@genesislcap/web-core';
import { logger } from '../utils';

// Define custom params interface
interface CustomRendererParams extends ICellRendererParams {
  onChange?: (value: any, params: CustomRendererParams) => void;
  isDisabled?: (rowData: any) => boolean;
}

export class CustomRenderer extends GenesisElement implements ICellRendererComp {
  @observable
  public params: CustomRendererParams;

  @observable
  public value: any;

  // Initialize renderer
  public init(params: CustomRendererParams) {
    if (!params) return;
    this.params = params;
    this.value = params.value;
  }

  // Required method to return GUI element
  public getGui(): HTMLElement {
    return this;
  }

  // Refresh method
  public refresh(params: CustomRendererParams): boolean {
    this.params = params;
    this.value = params.value;
    return true;
  }

  // Optional disable logic
  public isDisabled(data: any): boolean {
    if (typeof this.params?.isDisabled === 'function') {
      try {
        return this.params.isDisabled(data);
      } catch (error) {
        logger.error('Error in isDisabled callback:', error);
      }
    }
    return false;
  }

  // Handle value changes
  public changeHandler = (newValue: any) => {
    this.value = newValue;

    if (typeof this.params?.onChange === 'function') {
      this.params.onChange(newValue, this.params);
    }
  };
}

Component registration

Register custom components using the gridComponents property:

@customElement({
  name: 'my-grid',
  template: html`
    <rapid-grid-pro 
      :gridComponents="${(x) => x.gridComponents}"
      auto-cell-renderer-by-type>
      <grid-pro-client-side-datasource resource-name="ALL_TRADES">
      </grid-pro-client-side-datasource>
    </rapid-grid-pro>
  `
})
export class MyGrid extends GenesisElement {
  @observable gridComponents = {
    // Custom renderers
    customRenderer: CustomRenderer,
    customStatusPill: CustomStatusPillRenderer,
    
    // Custom editors
    customEditor: CustomEditor,
    advancedDateEditor: AdvancedDateEditor,
    
    // Custom filters
    customFilter: CustomFilter
  };
}

Key considerations

• Always implement ICellRendererComp for renderers or ICellEditorComp for editors.
• Use @observable for reactive properties.
• Provide flexible configuration options through cellRendererParams or cellEditorParams.
• Handle potential errors gracefully.
• Integrate with design system components.
• Ensure editors are registered in gridOptions.components.

Common patterns to follow

• All custom components implement the appropriate AG Grid interface (ICellRendererComp or ICellEditorComp).
• Use @observable decorators for reactive properties.
• Support custom disable logic through isDisabled functions.
• Integrate with the Foundation UI design system.
• Provide flexible configuration through parameters.
• Handle value changes and update grid data accordingly.
• Consider performance when generating dynamic options.
• Ensure proper focus management in editors with afterGuiAttached().

When creating custom renderers or editors for Grid Pro, follow these key steps:

• Initialize with the init() method.
• Implement getGui() to return the root element.
• Use refresh() to update the component state.
• Implement getValue() in editors to return the edited value.
• Provide optional disable logic with isDisabled().
• Support custom change handling.
• Handle potential errors in callbacks.
• Use appropriate value accessors.
• Consider the user experience, such as focusing the editor when it's opened.