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 the grid are as follows:
- Cell Component: To customise the contents of a cell.
- Header Component: To customise the header of a column and column groups.
- Edit Component: To customise the editing of a cell.
- Filter Component: For custom column filter that appears inside the column menu.
- Floating Filter: For custom column floating filter that appears inside the column menu.
- Date Component: To customise the date selection component in the date filter.
- Loading Component: To customise the loading cell row when using Server Side row model.
- Overlay Component: To customise loading and no rows overlay components.
- Status Bar Component: For custom status bar components.
- Tool Panel Component: For custom tool panel components.
- Tooltip Component: For custom cell tooltip components.
The remainder of this page gives information that is common across all the component types.
Declaring Custom Components
VueJS components can be defined as either simple inline components, or as full/complex externalised ones (i.e in a separate file).
"Inline" Components
export default {
data() {
return {
...data
}
},
components: {
AgGridVue, // the actual AgGridVue Grid component
CubeComponent: { // an inline custom component
template: '<span>{{ valueCubed() }}</span>',
methods: {
valueCubed() {
return this.params.value * this.params.value * this.params.value;
}
}
}
}
}
Note here that we can define the property name either quoted or not but note that in order to reference these components in your column definitions you'll need to provide them as case-sensitive strings.
Locally Declared Components
const SquareComponent = {
template: '<span>{{ valueSquared() }}</span>',
methods: {
valueSquared() {
return this.params.value * this.params.value;
}
}
};
Externalised JavaScript Components (.js files)
// SquareComponent.js
export default {
template: '<span>{{ valueSquared() }}</span>',
methods: {
valueSquared() {
return this.params.value * this.params.value;
}
}
};
Externalised Single File Components (SFC / .vue files)
<template>
<span class="currency">{{ params.value | currency('EUR') }}</span>
</template>
<script>
export default {
filters: {
currency(value, symbol) {
let result = value;
if (!isNaN(value)) {
result = value.toFixed(2);
}
return symbol ? symbol + result : result;
}
}
};
</script>
<style scoped>
.currency {
color: blue;
}
</style>
Note that in this case the component name will match the actual reference, but you can specify a different one if you choose:
components: {
AgGridVue,
'MySquareComponent': SquareComponent
}
All of the above works if you're going to register components by Name (see below). If you wish to register components by direct reference then you will need to wrap your component with defineComponent(...your component...)
.
We highly recommend registration by name for the flexibility it provides - all of our examples use registration by name.
Although the Composition API is supported we strongly encourage the use of the Options API for components that require callbacks (such as Cell Editors).
Full support for Composition API will be added soon but for now we do recommend the use of the Options API when writing Custom Components.
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. It is however useful here to step back and focus on the component registration process which is common across all component types.
There are generally two ways to register custom components ("inline" components can only be registered by name):
- By name
- Direct reference (deprecated)
Both options are fully supported by the grid - however we recommend referencing by name as registering by Direct Reference is deprecated. It's also the case that registering by name is the more flexible of the two options - given this, all of the examples in the documentation use registering by name. The direct reference approach is kept for backwards compatibility as this was the original way to do it in AG Grid.
Registering Inline Custom Components
Inline Custom Components can only be registered within the Grid by name:
<template>
<ag-grid-vue :columnDefs="columnDefs" ...other properties>
</ag-grid-vue>
</template>
<script>
//...other imports
import {AgGridVue} from "ag-grid-vue3";
export default {
components: {
AgGridVue,
CubeComponent: {
template: '<span>{{ valueCubed() }}</span>',
methods: {
valueCubed() {
return this.params.value * this.params.value * this.params.value;
}
}
}
},
data() {
return {
columnDefs: [
{
headerName: "Cube",
field: "value",
cellRenderer: 'CubeComponent',
}
]
}
}
//...other properties & methods
}
</script>
Registering Non-Inline Custom Components
1. By Name
To use a component within the grid you will reference components by case-sensitive name, for example:
<template>
<ag-grid-vue ...other properties>
</ag-grid-vue>
</template>
<script>
//...other imports
import {AgGridVue} from "ag-grid-vue3";
import CubeComponent from './CubeComponent.vue';
export default {
components: {
AgGridVue,
CubeComponent
}
data() {
return {
columnDefs: [
{
headerName: "Cube",
field: "value",
cellRenderer: 'CubeComponent'
}
]
}
}
//...other properties & methods
}
</script>
2. By Direct Reference
Deprecated.
This approach is supported but not recommend and will be removed in a future release.
When registering components within the Grid by direct reference the target components must be wrapped in defineComponent(...)
:
<template>
<ag-grid-vue ...other properties>
</ag-grid-vue>
</template>
<script>
//...other imports
import Vue from "vue";
import {AgGridVue} from "ag-grid-vue3";
const CubeComponent = defineComponent({
template: '<span>{{ valueCubed() }}</span>',
methods: {
valueCubed() {
return this.params.value * this.params.value * this.params.value;
}
}
};
export default {
components: {
AgGridVue,
// CubeComponent does not have to be registered here when registering by direct reference
}
data() {
return {
columnDefs: [
{
headerName: "Cube",
field: "value",
cellRenderer: CubeComponent
}
]
}
}
//...other properties & methods
}
</script>
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.
- No need to wrap components with
defineComponent(...)
Providing Additional Parameters
Each Custom Component gets a set of parameters from the grid. For example, for Cell Component the grid provides, among other things, the value to be rendered. You can provide additional properties to the Custom Component (e.g. what currency symbol to use) by providing additional parameters specific to your application.
To provide additional parameters, use the property [prop-name]Params
, e.g. cellRendererParams
.
<ag-grid-vue
:columnDefs="columnDefs"
/* other grid options ... */>
</ag-grid-vue>
this.columnDefs = [
{
field: 'price',
cellRenderer: PriceCellRenderer,
cellRendererParams: {
currency: 'EUR'
}
},
];
Mixing JavaScript and Vue
When providing Custom Components you have a choice of the following:
- Provide an AG Grid component in JavaScript.
- Provide an AG Grid component as an Vue Component.
For example if you want to build a cell renderer you have the choice to build the cell renderer using either Vue or using plain JavaScript.
The following code snippet shows how both JavaScript and Vue Components can be used at the same time:
<template>
<ag-grid-vue :components="components"
...other properties>
</ag-grid-vue>
</template>
<script>
//...other imports
import {AgGridVue} from "ag-grid-vue3";
import JavascriptComponent from './JavascriptComponent.js';
import VueComponent from './VueComponent.vue';
export default {
components: {
AgGridVue,
// Vue components are registered here
'vueComponent': VueComponent
}
data() {
return {
// JavaScript components are registered here, for when looking up component by name
components: {
// declare the javascript component
'javascriptComponent': JavascriptComponent
},
columnDefs: [
{
headerName: "JS Cell",
field: "value",
cellRenderer: 'javascriptComponent', // reference/use the javascript component by name
},
{
headerName: "JS Cell",
field: "value",
cellRenderer: JavascriptComponent, // reference/use the javascript component directly
},
{
headerName: "Vue Cell",
field: "value",
cellRenderer: 'vueComponent', // reference/use the Vue component
}
]
}
}
//...other properties & methods
}
</script>
Change the documentation view to JavaScript to see how to create a plain JavaScript component.
Child to Parent Communication
There are a variety of ways to manage component communication in Vue (shared service, local variables etc), but you often need a simple way to let a "parent" component know that something has happened on a "child" component. In this case the simplest route is to use the Grid's context
feature to hold a reference to the parent, which the child can then access.
// Parent Grid Component
<template>
<ag-grid-vue :context="context" ...other properties>
</ag-grid-vue>
</template>
<script>
//...other imports
import {AgGridVue} from "ag-grid-vue3";
import CubeComponent from './CubeComponent.vue';
export default {
components: {
AgGridVue
}
data() {
return {
context: {}
}
},
beforeMount() {
this.context = {
componentParent: this
}
},
methods: {
parentMethod() {
// do something
}
}
//...other properties & methods
}
</script>
// Child Grid Component
<template>
<ag-grid-vue ...other properties>
</ag-grid-vue>
</template>
<script>
//...other imports
export default {
methods: {
doSomethingOnGrid() {
// the grid component can now be accessed via this.params.context.componentParent
this.params.context.componentParent.parentMethod()
}
}
//...other properties & methods
}
</script>
Note that although we've used componentParent
as the property name here it can be anything - the main point is that you can use the context
mechanism to share information between the components.
Provide/Inject
When using Vue Components within AG Grid you are able to use provide
/ context
, but only in the Options
format below:
// Parent Grid
const VueExample = {
template: `
<ag-grid-vue
style="width: 100%; height: 100%;"
class="ag-theme-quartz"
:columnDefs="columnDefs"
:rowData="rowData">
</ag-grid-vue>
`,
components: {
'ag-grid-vue': AgGridVue,
'myRenderer': MyRenderer
},
provide: {
'providedValue': 'testValue' // provide this value to grid components
},
//...rest of the component definition
}
// Child Grid Component
export default {
name: 'myRenderer',
template: `<span>{{ value }} {{ test }}</span>`,
inject: ['providedValue'], // retrieve/inject the provided value
//...rest of the component definition
};
You cannot use the new Composition API (inject/provide) as this is not supported by Vue when using createNode createVNode
, but the above is a workable alternative.
Alternatively you could consider using the Grid's Context mechanism to share data with child components.
Component Usage
The below table gives a summary of the components, where they are configured and using what attribute.
Component | Where | Attribute |
---|---|---|
Cell Component | Column Definition | cellRenderer cellRendererParams cellRendererSelector |
Editor Component | Column Definition | cellEditor cellEditorParams cellEditorSelector |
Filter | Column Definition | filter filterParams |
Floating Filter | Column Definition | floatingFilter floatingFilterParams |
Header Component | Column Definition | headerComponent headerComponentParams |
Header Group Component | Column Definition | headerGroupComponent headerGroupComponentParams |
Tooltip Component | Column Definition | tooltipComponent tooltipComponentParams |
Group Row Cell Component | Grid Option | groupRowRenderer groupRowRendererParams |
Group Row Inner Cell Component | Grid Option | innerRenderer innerRendererParams |
Detail Cell Component | Grid Option | detailCellRenderer detailCellRendererParams |
Full Width Cell Component | Grid Option | fullWidthCellRenderer fullWidthCellRendererParams |
Loading Cell Component | Grid Option Column Definition | loadingCellRenderer loadingCellRendererParams |
Loading Overlay | Grid Option | loadingOverlayComponent loadingOverlayComponentParams |
No Rows Overlay | Grid Option | noRowsOverlayComponent noRowsOverlayComponentParams |
Drag and Drop Image | Grid Option | dragAndDropImageComponent dragAndDropImageComponentParams |
Date Component | Grid Option | dateComponent dateComponentParams |
Status Bar Component | Grid Option -> Status Bar | statusPanel statusPanelParams |
Tool Panel | Grid Option -> Side Bar | toolPanel toolPanelParams |
Menu Item | Grid Option -> Menu | menuItem menuItemParams |
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.
Drag And Drop | |
---|---|
agDragAndDropImage | Default cover element when grid parts are being dragged |
Date Inputs | |
---|---|
agDateInput | Default date input used by filters |
Column Headers | |
---|---|
agColumnHeader | Default column header |
agColumnHeaderGroup | Default column group header |
Column Filters | |
---|---|
agSetColumnFilter (e) | Set filter (default when using AG Grid Enterprise) |
agTextColumnFilter | Simple text filter (default when using AG Grid Community) |
agNumberColumnFilter | Number filter |
agDateColumnFilter | Date filter |
agMultiColumnFilter (e) | Multi filter |
agGroupColumnFilter (e) | Group column filter |
Floating Filters | |
---|---|
agSetColumnFloatingFilter (e) | Floating set filter |
agTextColumnFloatingFilter | Floating text filter |
agNumberColumnFloatingFilter | Floating number filter |
agDateColumnFloatingFilter | Floating date filter |
agMultiColumnFloatingFilter (e) | Floating multi filter |
agGroupColumnFloatingFilter (e) | Floating group column filter |
Cell Components | |
---|---|
agAnimateShowChangeCellRenderer | Cell Component that animates value changes |
agAnimateSlideCellRenderer | Cell Component that animates value changes |
agGroupCellRenderer | Cell Component for displaying group information |
agLoadingCellRenderer (e) | Cell Component for loading row when using Enterprise row model |
agSkeletonCellRenderer (e) | Cell Component for displaying skeleton cells |
agCheckboxCellRenderer | Cell Component that displays a checkbox for boolean values |
Overlays | |
---|---|
agLoadingOverlay | Loading overlay |
agNoRowsOverlay | No rows overlay |
Cell Editors | |
---|---|
agTextCellEditor | Text cell editor |
agSelectCellEditor | Select cell editor |
agRichSelectCellEditor (e) | Rich select editor |
agLargeTextCellEditor | Large text cell editor |
agNumberCellEditor | Number cell editor |
agDateCellEditor | Date cell editor |
agDateStringCellEditor | Date represented as string cell editor |
agCheckboxCellEditor | Checkbox cell editor |
Master Detail | |
---|---|
agDetailCellRenderer (e) | Detail panel for master / detail grid |
Column Menu / Context Menu | |
---|---|
agMenuItem (e) | Menu item within column or context menu |
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:
- agDragAndDropImage: To change the default drag and drop image when dragging grid parts.
- 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.
- agSkeletonCellRenderer: To change the default skeleton loading cell renderer for Enterprise Row Model.
- agLoadingOverlay: To change the default 'loading' overlay.
- agNoRowsOverlay: To change the default 'no rows' overlay.
- agCellEditor: To change the default cell editor.
- agDetailCellRenderer: To change the default detail panel for master / detail grids.
- agMenuItem: To change the default menu item for column and context menus.
To override the default component, register the custom component in the GridOptions components
property under the above name.
const MyApp = {
// Here is where we specify the components to be used instead of the default
components: {
'ag-grid-vue': AgGridVue
agDateInput: CustomDateComponent,
agColumnHeader: CustomHeaderComponent
},
Overridable grid components are the only components you need to additionally specify with components
in order to tie their usage to the actual component. All other registration types specify their usage in column definitions or on the AgGridVue
component itself.
For an example of this please refer to the Date Component documentation.