Framework:javascriptangularreactvue

Components

You can create your own custom components to customise the behaviour of the grid. For example you can customise how cells are rendered, how values are edited and also create your own filters.

The full list of component types you can provide in ag-Grid are as follows:

The remainder of this page gives information that is common across all the component types.

Registering Custom Components

The pages for each component type (cell renderer, cell editor etc) contain examples on how to register and use each component type. However it is useful here to step back and focus on the component registration process which is common across all component types and all frameworks (React, Angular etc).

There are two ways to register custom components:

  • By name.
  • Direct reference.

Both options are fully supported by the grid, however the preferred options is by name as it's more flexible. All of the examples in the documentation use this approach. The direct reference approach is kept for backwards compatibility reasons as this was the original way to do it in ag-Grid.

1. By Name

A component is registered with the grid by providing it through the components grid property. The components grid property contains a map of 'component names' to 'component classes'. Components of all types (editors, renderers, filters etc) are all stored together and must have unique names.

gridOptions = {

    // register the components using 'components' grid property
    components: {
        // 'countryCellRenderer' is mapped to class CountryCellRenderer
        countryCellRenderer: CountryCellRenderer,
        // 'countryFilter' is mapped to class CountryFilter
        countryFilter: CountryFilter
    },

    // then refer to the component by name
    columnDefs: [
        {
            field: 'country',
            cellRenderer: 'countryCellRenderer',
            filter: 'countryFilter'
        },
    ],

    ...
}

2. Direct Reference

A shorter approach is to refer to the component class directly.

gridOptions = {

    columnDefs: [
        {
            field: 'country',
            cellRenderer: CountryCellRenderer,
            filter: CountryFilter
        },
    ],

    ...
}

Advantages of By Name

Registering components by name has the following advantages:

  • Implementations can change without having to change all the column definitions. For example, you may have 20 columns using a currency cell renderer. If you want to update the cell renderer to another currency cell renderer, you only need to do it in only place (where the cell renderer is registered) and all columns will pick up the new implementation.
  • The part of the grid specifying column definitions is plain JSON. This is helpful for applications that read column definitions from static data. If you referred to the class name directly inside the column definition, it would not be possible to convert the column definition to JSON.

Registering Framework Components

Most of the frameworks ag-Grid works with use components. It is possible to use the framework components inside of ag-Grid. Configuring the components is same and explained in this section. The frameworks that follow this conventions are:

  • Angular (version 2 and later)
  • React
  • VueJS
  • Polymer

If you are using one of the supported frameworks registration is done using the frameworkComponents property rather than the components property. Then the component is registered by name as normal.

gridOptions = {
    // use frameworkComponents instead of components. most frameworks will allow you
    // to specify this as a bound property.
    frameworkComponents: {
        countryCellRenderer: AngularCountryCellRenderer,
        countryFilter: AngularCountryFilter
    },

    // then refer to the component by name as before
    columnDefs: [
        {
            field: 'country',
            cellRenderer: 'countryCellRenderer',
            filter: 'countryFilter'
        },
    ],

    ...
}

You can also refer to the component classes directly using the framework variant of the property. For example instead of using cellRenderer you use cellRendererFramework.

gridOptions = {

    columnDefs: [
        {
            field: 'country',
            cellRendererFramework: CountryCellRenderer,
            filterFramework: CountryFilter
        },
    ],

    ...
}

Summary of Component Registration

Here we give an overview, as there is a lot of similar sounding information above.

The grid options has the following properties for registering components:

Component Registration

componentsA map of component names to plain JavaScript components.
frameworkComponentsA map of component names to framework (React, Angular etc) components.

Component Usage

The below table gives an overview of where components can be used. The table shows both options for usage:

  • Name / Direct JavaScript: This can be: 1) A component name referring to a registered component (either plain JavaScript or framework component); 2) A direct reference to a JavaScript component.
  • Direct Framework: A direct reference to a framework (React, Angular etc) component.
ComponentWhereName / Direct JavaScriptDirect Framework
Detail Cell RendererGrid OptiondetailCellRendererdetailCellRendererFramework
Full Width Cell RendererGrid OptionfullWidthCellRendererfullWidthCellRendererFramework
Group Row Cell RendererGrid OptiongroupRowRenderergroupRowRendererFramework
Group Row Inner Cell RendererGrid OptiongroupRowInnerRenderergroupRowInnerRendererFramework
Loading Cell RendererGrid OptionloadingCellRendererloadingCellRendererFramework
Loading OverlayGrid OptionloadingOverlayRendererloadingOverlayRendererFramework
No Rows OverlayGrid OptionnoRowsOverlayRenderernoRowsOverlayRendererFramework
Date ComponentGrid OptiondateComponentdateComponentFramework
Status Bar ComponentGrid Option -> Status BarstatusPanelstatusPanelFramework
Cell RendererColumn DefinitioncellRenderercellRendererFramework
Pinned Row Cell RendererColumn DefinitionpinnedRowCellRendererpinnedRowCellRendererFramework
Cell EditorColumn DefinitioncellEditorcellEditorFramework
FilterColumn DefinitionfilterfilterFramework
Floating FilterColumn DefinitionfloatingFilterComponentfloatingFilterComponentFramework
Header ComponentColumn DefinitionheaderComponentheaderComponentFramework
Header Group ComponentColumn DefinitionheaderGroupComponentheaderGroupComponentFramework

JavaScript or Framework

If you are using a framework, then you have a choice of the following:

  1. Provide an ag-Grid component in JavaScript.
  2. Provide an ag-Grid component as a framework component (eg React or Angular).

For example if you want to build a cell renderer and you are using React, you have the choice to build the cell renderer using React or using plain JavaScript.

If using a framework, you should first read how to build the component using plain JavaScript. This is because the framework specific component builds on what you learn from the JavaScript component.

Mixing JavaScript and Framework

It is possible to mix JavaScript and framework components in the same application. The following code snippet shows how such can be configured:

gridOptions = {
    // JavaScript components registered here
    components: {
        countryFilter: CustomCountryFilter
    },

    // Framework components registered here
    frameworkComponents: {
        countryCellRenderer: CountryCellRenderer
    },

    columnDefs: [ {
        field: 'country',

        // filter is a registered plain JavaScript component
        filter: 'countryFilter',

        // cell renderer is a registered framework (React, Angular etc) component
        cellRenderer: 'countryCellRenderer'
    } ]
};

Grid Provided Components

The grid comes with pre-registered components that can be used. Each component provided by the grid starts with the namespaces 'ag' to minimise naming conflicts with user provided components. The full list of grid provided components are in the table below.

Date Inputs

agDateInput Default date input used by filters.

Column Headers

agColumnHeader Default column header.
agColumnHeaderGroup Default column group header.

Column Filters

agSetColumnFilter Set filter (default when using ag-Grid Enterprise).
agTextColumnFilter Simple text filter (default when using ag-Grid Free).
agNumberColumnFilter Number filter.
agDateColumnFilter Date filter.

Floating Filters

agSetColumnFloatingFilter Floating set filter.
agTextColumnFloatingFilter Floating text filter.
agNumberColumnFloatingFilter Floating number filter.
agDateColumnFloatingFilter Floating date filter.

Cell Renderers

agAnimateShowChangeCellRenderer Cell renderer that animates value changes.
agAnimateSlideCellRenderer Cell renderer that animates value changes.
agGroupCellRenderer Cell renderer for displaying group information.
agLoadingCellRenderer Cell editor for loading row when using Enterprise row model.

Overlays

agLoadingOverlay Loading overlay.
agNoRowsOverlay No rows overlay.

Cell Editors

agTextCellEditor Text cell editor.
agSelectCellEditor Select cell editor.
agRichSelectCellEditor Rich select editor.
agPopupTextCellEditor Popup text cell editor.
agPopupSelectCellEditor Popup select cell editor.
agLargeTextCellEditor Large text cell editor.

Master Detail

agDetailCellRenderer Detail panel for master / detail grid.

Overriding Grid Components

It is also possible to override components. Where the grid uses a default value, this means the override component will be used instead. The default components, where overriding makes sense, are as follows:

  • agDateInput: To change the default date selection across all filters.
  • agColumnHeader: To change the default column header across all columns.
  • agColumnGroupHeader: To change the default column group header across all columns.
  • agLoadingCellRenderer: To change the default loading cell renderer for Enterprise Row Model.
  • agLoadingOverlay: To change the default 'loading' overlay.
  • agNoRowsOverlay: To change the default loading 'no rows' overlay.
  • agTextCellEditor: To change the default text cell editor.
  • agDetailCellRenderer: To change the default detail panel for master / detail grids.