AG-Grid-React-Series-#26-Custom-Cell-Editors-in-AG-Grid

Why Custom Cell Editors?

• Tailored User Experience: Implement complex input types like date pickers, color selectors, multi-select dropdowns, or even file upload buttons directly within a cell.
• Advanced Validation: Enforce business logic during data entry that goes beyond simple data type checks.
• Integration with External Components: Seamlessly embed third-party React components or your own reusable UI components as cell editors.
• Improved Accessibility: Provide more intuitive and accessible editing controls for users with specific needs.

The Core: AG-Grid's React Cell Editor Interface

When you create a custom cell editor in React for AG-Grid, your component needs to adhere to a specific interface and provide certain methods that AG-Grid can call. The primary interface for React is essentially an object with methods that AG-Grid expects. Let's break down the key elements:

1. The init(params) Method (or equivalent in functional components)

In a class component, this is an actual method. For functional components using React hooks, you'll typically manage this through the component's state and props. The params object passed by AG-Grid contains crucial information about the cell being edited:

• value: The current value of the cell.
• colDef: The column definition for the column being edited.
• column: The column object.
• node: The row node object.
• api: The AG-Grid API instance.
• columnApi: The AG-Grid Column API instance.
• onEditingStopped: A callback function to notify the grid that editing has finished.
• stopEditing: A function to stop editing programmatically.
• cellStartedEdit: Boolean indicating if the cell was started with a key press.
• charPress: The character that caused the edit to start (if any).
• keyPress: The key that caused the edit to start (if any).
• eGridCell: The DOM element of the cell.
• eInput: For some built-in editors, the input element.
• cellEditorParams: Any custom parameters defined in your columnDefs.

2. Essential Methods for AG-Grid Interaction

These methods are what AG-Grid calls on your editor component to manage the editing lifecycle.

• getValue():

  This is the most critical method. AG-Grid calls this method when it needs to retrieve the new value from your editor. Your component must return the value that should be stored in the grid.

• isPopup():

  (Optional) If your editor should appear as a popup (e.g., a calendar picker appearing over other cells), this method should return true. By default, editors appear inline within the cell.

• afterGuiAttached():

  (Optional) Called after the editor's GUI has been rendered and attached to the DOM. This is an ideal place to focus an input element or perform any post-rendering setup.

• isCancelBeforeStart():

  (Optional) Return true if you want to cancel the editing before it even starts (e.g., if a certain condition isn't met based on the initial value or cell state).

• isCancelAfterEnd():

  (Optional) Return true if you want to cancel the editing after the user attempts to finish it (e.g., if the entered value fails validation). If cancelled, the original cell value is retained.

• focusIn():

  (Optional) Called by AG-Grid when it wants your editor to take focus. This is especially useful if your editor has multiple focusable elements and you want to control which one gets initial focus.

For functional React components, you expose these methods using useImperativeHandle in conjunction with forwardRef.

Building a Simple Custom Text Editor

Let's start by creating a basic custom text editor that allows a user to modify a text value, and then automatically focuses the input when editing starts.

1. Create the React Component (MySimpleTextEditor.jsx)

This component will be a functional React component that uses hooks to manage its state and expose its methods to AG-Grid.

import React, { useState, useRef, useEffect, useImperativeHandle, forwardRef } from 'react';

const MySimpleTextEditor = forwardRef((props, ref) => {
    const [value, setValue] = useState(props.value);
    const inputRef = useRef(null);

    // Expose AG-Grid methods
    useImperativeHandle(ref, () => {
        return {
            // This is the most important method - returns the value of the editor
            getValue() {
                return value;
            },

            // Called once the editor is in the DOM
            afterGuiAttached() {
                if (inputRef.current) {
                    inputRef.current.focus();
                    inputRef.current.select(); // Select all text for easy replacement
                }
            },

            // Optional: for validation, cancel editing if condition is met
            isCancelAfterEnd() {
                // Example: Prevent saving if value is empty
                return value === null || value === undefined || value.trim() === '';
            },

            // Optional: Focus the input when AG-Grid wants it to be focused
            focusIn() {
                if (inputRef.current) {
                    inputRef.current.focus();
                }
            }
        };
    });

    const handleChange = (event) => {
        setValue(event.target.value);
    };

    // AG-Grid will automatically stop editing on Enter, Tab, etc.
    // If you need custom keyboard handling, you can add an onKeyDown handler here.

    return (
        <input
            ref={inputRef}
            type="text"
            value={value}
            onChange={handleChange}
            style={{ width: '100%', height: '100%', border: 'none', outline: 'none' }}
        />
    );
});

export default MySimpleTextEditor;
        

2. Integrate into AG-Grid's columnDefs

Now, tell AG-Grid to use your custom component for a specific column. You do this by setting the cellEditor property in your columnDefs.

import React, { useState, useCallback, useMemo } from 'react';
import { AgGridReact } from 'ag-grid-react';
import 'ag-grid-community/styles/ag-grid.css';
import 'ag-grid-community/styles/ag-theme-alpine.css';

import MySimpleTextEditor from './MySimpleTextEditor'; // Import your custom editor

const GridComponent = () => {
    const [rowData] = useState([
        { id: 1, make: 'Toyota', model: 'Celica', price: 35000 },
        { id: 2, make: 'Ford', model: 'Mondeo', price: 32000 },
        { id: 3, make: 'Porsche', model: 'Boxster', price: 72000 },
    ]);

    const [columnDefs] = useState([
        {
            field: 'make',
            editable: true,
            cellEditor: MySimpleTextEditor, // Use your custom editor here
            // You can pass custom parameters to your editor via cellEditorParams
            // cellEditorParams: {
            //     maxLength: 20
            // }
        },
        { field: 'model', editable: true },
        { field: 'price', editable: true },
    ]);

    const defaultColDef = useMemo(() => {
        return {
            flex: 1,
            minWidth: 100,
            resizable: true,
        };
    }, []);

    const onGridReady = useCallback((params) => {
        // You might want to auto-size columns here
        params.api.sizeColumnsToFit();
    }, []);

    return (
        <div className="ag-theme-alpine" style={{ height: 400, width: 600 }}>
            <AgGridReact
                rowData={rowData}
                columnDefs={columnDefs}
                defaultColDef={defaultColDef}
                onGridReady={onGridReady}
                editType="fullRow" // Or 'cell' for individual cell editing
            />
        </div>
    );
};

export default GridComponent;
        

With this setup, when you double-click on a cell in the 'Make' column, your custom MySimpleTextEditor will pop up, automatically focus its input, and allow you to type. If you try to save an empty value, it will cancel the edit (due to isCancelAfterEnd).

Advanced Custom Editor: A Dropdown Selector

Let's create a slightly more complex custom editor: a dropdown (<select>) that receives its options via cellEditorParams.

1. Create the React Component (MyDropdownEditor.jsx)

import React, { useState, useEffect, useRef, useImperativeHandle, forwardRef } from 'react';

const MyDropdownEditor = forwardRef((props, ref) => {
    // Initial value for the dropdown, falling back to the first option if none matches
    const initialValue = props.value;
    const options = props.colDef.cellEditorParams ? props.colDef.cellEditorParams.options : [];
    
    // Ensure initialValue is one of the options, or default to the first option
    const [value, setValue] = useState(
        options.includes(initialValue) ? initialValue : (options.length > 0 ? options[0] : '')
    );
    const selectRef = useRef(null);

    useImperativeHandle(ref, () => {
        return {
            getValue() {
                return value;
            },
            afterGuiAttached() {
                if (selectRef.current) {
                    selectRef.current.focus();
                }
            },
            focusIn() {
                if (selectRef.current) {
                    selectRef.current.focus();
                }
            }
        };
    });

    const handleChange = (event) => {
        setValue(event.target.value);
    };

    return (
        <select
            ref={selectRef}
            value={value}
            onChange={handleChange}
            style={{ width: '100%', height: '100%', border: 'none', outline: 'none' }}
        >
            {options.map((option, index) => (
                <option key={index} value={option}>
                    {option}
                </option>
            ))}
        </select>
    );
});

export default MyDropdownEditor;
        

2. Integrate into AG-Grid's columnDefs with cellEditorParams

Now, let's update our GridComponent to use this dropdown editor for a column, passing the available options via cellEditorParams.

// ... (imports remain the same, add MyDropdownEditor)
import MyDropdownEditor from './MyDropdownEditor';

const GridComponent = () => {
    const [rowData] = useState([
        { id: 1, make: 'Toyota', model: 'Celica', type: 'Sedan', price: 35000 },
        { id: 2, make: 'Ford', model: 'Mondeo', type: 'SUV', price: 32000 },
        { id: 3, make: 'Porsche', model: 'Boxster', type: 'Sports Car', price: 72000 },
    ]);

    const [columnDefs] = useState([
        {
            field: 'make',
            editable: true,
            cellEditor: MySimpleTextEditor,
        },
        { field: 'model', editable: true },
        {
            field: 'type',
            editable: true,
            cellEditor: MyDropdownEditor, // Use your custom dropdown editor
            cellEditorParams: {
                options: ['Sedan', 'SUV', 'Hatchback', 'Coupe', 'Sports Car', 'Truck'] // Pass options here
            }
        },
        { field: 'price', editable: true },
    ]);

    // ... (rest of the component remains the same)

    return (
        <div className="ag-theme-alpine" style={{ height: 400, width: '100%' }}>
            <AgGridReact
                rowData={rowData}
                columnDefs={columnDefs}
                defaultColDef={defaultColDef}
                onGridReady={onGridReady}
                editType="fullRow"
            />
        </div>
    );
};

export default GridComponent;
        

Now, the 'Type' column will show a native HTML <select> element with predefined options when edited. The cellEditorParams are dynamically passed to your editor component, making it highly reusable.

Tips for Effective Custom Cell Editors

• Keep it Lightweight: Editors should be responsive and render quickly. Avoid complex logic or heavy rendering within the editor itself.
• Accessibility: Ensure your custom editors are accessible. Use proper ARIA attributes, keyboard navigation, and clear focus management.
• Error Handling and Validation: Utilize isCancelBeforeStart() and isCancelAfterEnd() for server-side or complex client-side validation.
• Event Handling: Your editor component can emit events or use callbacks passed via cellEditorParams if it needs to interact with the parent grid component beyond just returning a value.
• Styling: Your editor components will inherit some grid styles. You might need to apply specific styles to ensure they blend well or stand out as intended. Consider using styled-components or CSS modules for isolated styling.
• Popup Editors: For editors like date pickers or complex dialogs, set isPopup() to true. AG-Grid will manage their positioning relative to the cell, but you'll need to handle closing them.
• Keyboard Navigation: For non-standard inputs, you might need to handle onKeyDown events to prevent default grid behavior (like stopping editing on Enter or Tab) if your editor uses those keys internally.