Angular Data GridRich Select Cell Editor

Enterprise

An alternative to using the browser's select popup for dropdowns inside the grid.

The Rich Select Cell Editor allows users to enter a cell value from a list of provided values by searching or filtering the list.

Enabling Rich Select Cell Editor

Edit any cell in the grid below to see the Rich Select Cell Editor.

Enabled with agRichSelectCellEditor and configured with IRichCellEditorParams.

columnDefs: [
    {
        cellEditor: 'agRichSelectCellEditor',
        cellEditorParams: {
            values: ['English', 'Spanish', 'French', 'Portuguese', '(other)'],
        }
        // ...other props
    }
]

Benefits over browser's select are as follows:

  • Uses DOM row virtualisation so very large lists can be displayed.
  • Integrates with the grid perfectly, avoiding glitches seen with the standard select.
  • Uses HTML to render the values: you can provide cell renderers to customise what each value looks like.

Customisation

Cell Renderer

The cell renderer used within the editor can be customised as shown below:

columnDefs: [
    {
        cellEditor: 'agRichSelectCellEditor',
        cellRenderer: ColourCellRenderer,
        cellEditorParams: {
            values: ['AliceBlue', 'AntiqueWhite', 'Aqua', /* .... many colours */ ],
            cellRenderer: ColourCellRenderer,
            valueListMaxHeight: 220
        }
        // ...other props
    }
]

The interface for the Rich CellEditor Component is as follows:

interface ICellEditorRendererAngularComp {
   // Mandatory - Params for rendering
   agInit(params: IRichCellEditorRendererParams): void;
}

The Component is provided props containing, amongst other things, the value to be rendered.

class MyCustomEditorRenderer implements ICellEditorRendererAngularComp {
  // ...
  agInit(props: IRichCellEditorRendererParams): void {
    this.value = props.value;
  }
  // ...

The provided props (interface IRichCellEditorRendererParams) are:

value
TValue[] | TValue | null
The value to be rendered by the renderer
valueFormatted
string
The value to be renderer by the renderer formatted by the editor
getValue
Function
Gets the current value of the editor
setValue
Function
Sets the value of the editor
setTooltip
Function
Used to set a tooltip to the renderer
The grid api.
context
TContext
Application context as set on gridOptions.context.

Search Values

Different types of search are possible within the editor list as shown below:

columnDefs: [
    {
        cellEditor: 'agRichSelectCellEditor',
        cellRenderer: ColourCellRenderer,
        cellEditorParams: {
            values: ['AliceBlue', 'AntiqueWhite', 'Aqua', /* .... many colours */ ],
            allowTyping: true,
            filterList: true,
            highlightMatch: true,
            valueListMaxHeight: 220
        }
        // ...other props
    }
]

Allow Typing

The editor input can be configured to allow text input, which is used to match different parts of the editor list items as shown below:

columnDefs: [
    {
        cellEditor: 'agRichSelectCellEditor',
        cellRenderer: ColourCellRenderer,
        cellEditorParams: {
            values: ['AliceBlue', 'AntiqueWhite', 'Aqua', /* .... many colours */ ],
            allowTyping: true,
            filterList: true,
            highlightMatch: true,
            valueListMaxHeight: 220
        }
        // ...other props
    }
]

Format Values

Items in the editor list can be formatted as shown below:

columnDefs: [
    {
        cellEditor: 'agRichSelectCellEditor',
        cellEditorParams: {
            values: ['English', 'Spanish', 'French', 'Portuguese', '(other)'],
            formatValue: value => value.toUpperCase()
        }
        // ...other props
    }
]

Complex Objects

When working with objects as values, you need to specify a keyCreator function within the column definition to enable more complex features of the rich select cell editor.

The Key Creator generates a unique string key from the complex object which is used for grouping, Set filtering, and searching within the cell editor dropdown.

const colors = [
  { name: "Pink", code: "#FFC0CB" },
  // ...other values
];

columnDefs: [
    {
        cellEditor: 'agRichSelectCellEditor',
        keyCreator: params => params.value.name,
        cellEditorParams: {
            values: colors,
            formatValue: value => value.toUpperCase()
        }
        // ...other props
    }
]

Multi Selection

The editor can be configured to allow the selection of multiple values as shown below:

columnDefs: [
    {
        cellEditor: 'agRichSelectCellEditor',
        cellEditorParams: {
            values: ['AliceBlue', 'AntiqueWhite', 'Aqua', /* .... many colours */ ],
            multiSelect: true,
            searchType: 'matchAny',
            filterList: true,
            highlightMatch: true,
            valueListMaxHeight: 220
        }
        // ...other props
    }
]

Async Values

List values can be provided asynchronously to the editor as shown below:

The values property can receive a Promise that resolves an array of values.

function getValueFromServer(params: ICellEditorParams): Promise<string[]> {
  return new Promise((resolve) => {
    setTimeout(() => resolve(['English', 'Spanish', 'French', 'Portuguese', '(other)']), 1000);
  });
}
columnDefs: [
    {
        cellEditor: 'agRichSelectCellEditor',
        cellEditorParams: {
            values: getValueFromServer(),
        }
        // ...other props
    }
]

API Reference

Properties available on the IRichCellEditorParams<TData = any, TValue = any> interface.

values
TValue[] | RichCellEditorValuesCallback
The list of values to be selected from.
cellHeight
number
The row height, in pixels, of each value.
cellRenderer
any
The cell renderer to use to render each value. Cell renderers are useful for rendering rich HTML values, or when processing complex data.
allowTyping
boolean
default: false
Set to true to be able to type values in the display area.
filterList
boolean
default: false
If true it will filter the list of values as you type (only relevant when allowTyping=true).
searchType
'match' | 'matchAny' | 'fuzzy'
default: 'fuzzy'
The type of search algorithm that is used when searching for values.
  • match - Matches if the value starts with the text typed.
  • matchAny - Matches if the value contains the text typed.
  • fuzzy - Matches the closest value to text typed.
  • Note: When a cellRenderer is specified, this option will not work.
    highlightMatch
    boolean
    default: false
    If true, each item on the list of values will highlight the part of the text that matches the input. Note: It only makes sense to use this option when filterList is true and searchType is not fuzzy.
    multiSelect
    boolean
    If true this component will allow multiple items from the list of values to be selected. Note: This feature does not work with allowTyping=true.
    suppressDeselectAll
    boolean
    If true the option to remove all selected options will not be displayed. Note: This feature only works when multiSelect=true.
    suppressMultiSelectPillRenderer
    boolean
    When multiSelect=true the editor will automatically show the selected items as "pills". Set this property to true suppress this behaviour.
    searchDebounceDelay
    number
    default: 300
    The value in ms for the search algorithm debounce delay (only relevant when allowTyping=false).
    valuePlaceholder
    string
    A string value to be used when no value has been selected.
    valueListGap
    number
    default: 4
    The space in pixels between the value display and the list of items.
    valueListMaxHeight
    number | string
    default: 'calc(var(--ag-row-height) * 6.5)'
    The maximum height of the list of items. If the value is a number it will be treated as pixels, otherwise it should be a valid CSS size string.
    valueListMaxWidth
    number | string
    The maximum width of the list of items. If the value is a number it will be treated as pixels, otherwise it should be a valid CSS size string. Default: Width of the cell being edited.
    formatValue
    Function
    A callback function that allows you to change the displayed value for simple data.

    Continue to the next section: Number Cell Editor.