Row dragging is used to rearrange rows by dragging the row with the mouse. To enable row dragging, set the column property rowDrag
on one (typically the first) column.
Enabling Row Dragging
boolean or Function . Set to true (or return true from function) to allow row dragging. |
To enable row dragging on all columns, set the column property rowDrag = true
on one (typically the first) column.
const [columnDefs, setColumnDefs] = useState([
// make all rows draggable
{ field: 'athlete', rowDrag: true },
]);
<AgGridReact columnDefs={columnDefs} />
It is also possible to dynamically control which rows are draggable by providing a callback function as shown below:
const [columnDefs, setColumnDefs] = useState([
// only allow non-group rows to be dragged
{ field: 'athlete', rowDrag: params => !params.node.group },
]);
<AgGridReact columnDefs={columnDefs} />
There are two ways in which row dragging works in the grid, managed and unmanaged:
- Managed Dragging: This is the simplest, where the grid will rearrange rows as you drag them.
- Unmanaged Dragging: This is more complex and more powerful. The grid will not rearrange rows as you drag. Instead the application is responsible for responding to events fired by the grid and rows are rearranged by the application.
Managed Dragging
In managed dragging, the grid is responsible for rearranging the rows as the rows are dragged. Managed dragging is enabled with the property rowDragManaged=true
.
The example below shows simple managed dragging. The following can be noted:
- The first column has
rowDrag=true
which results in a draggable area being included in the cell. - The property
rowDragManaged
is set, to tell the grid to move the row as the row is dragged. - If a sort (click on the header) or filter (open up the column menu) is applied to the column, the draggable icon for row dragging is hidden. This is consistent with the constraints explained after the example.
The logic for managed dragging is simple and has the following constraints:
- Works with Client-Side row model only; not with the Infinite, Server-Side or Viewport row models.
- Does not work if Pagination is enabled.
- Does not work when sorting is applied. This is because the sort order of the rows depends on the data and moving the data would break the sort order.
- Does not work when filtering is applied. This is because a filter removes rows making it impossible to know what 'real' order of rows when some are missing.
- Does not work when row grouping or pivot is active. This is because moving rows between groups would require a knowledge of the underlying data which only your application knows.
These constraints can be bypassed by using unmanaged row dragging.
Suppress Move When Dragging
By default, the managed row dragging moves the rows while you are dragging them. This effect might not be desirable due to your application design. To prevent this default behaviour, set suppressMoveWhenRowDragging
to true
in the gridOptions
.
Multi-Row Dragging
It is possible to drag multiple rows at the same time, when rowDragMultiRow
is set to true
in the gridOptions
and it is combined with rowSelection.mode='multiRow'
.
For this example note the following:
- When you select multiple items and drag one of them, all items in the selection will be dragged.
- When you drag an item that is not selected while other items are selected, only the unselected item will be dragged.
Unmanaged Dragging
Unmanaged dragging is the default dragging for the grid. To use it, do not set the property rowDragManaged
. Unmanaged dragging differs from managed dragging in the following ways:
- The grid does not manage moving of the rows. The only thing the grid responds with is firing drag events. It is up to the application to do the moving of the rows (if that is what the application wants to do).
- Dragging is allowed while sort is applied.
- Dragging is allowed while filter is applied.
- Dragging is allowed while row group or pivot is applied.
It is not possible for the grid to provide a generic solution for row dragging that fits all usage scenarios. The way around this is the grid fires events and the application is responsible for implementing what meets the application's requirements.
Row Drag Events
There are four grid events associated with row dragging which are:
rowDragEnter
: A drag has started, or dragging already started and the mouse has re-entered the grid having previously left the grid.rowDragMove
: The mouse has moved while dragging.rowDragLeave
: The mouse has left the grid while dragging.rowDragEnd
: The drag has finished over the grid.rowDragCancel
: The drag has cancelled over the grid.
Typically a drag will fire the following events:
rowDragEnter
fired once - The drag has started.rowDragMove
fired multiple times - The mouse is dragging over the rows.rowDragEnd
fired once - The drag has finished.
Additional rowDragLeave
and rowDragEnter
events are fired if the mouse leaves or re-enters the grid. If the drag is finished outside of the grid, then the rowDragLeave
is the last event fired and no rowDragEnd
is fired, as the drag did not end on the grid.
When the Grid is created, a Drop Zone that is responsible for firing all the Row Drag Events is added to the Grid Body. This why Row Drag Events (including rowDragEnd
) are only fired when they happen on top of the Grid. If you need to monitor when a Row Drag ends outside of the Grid, for example, use the DragStopped event.
Each of the four row drag events extend the RowDragEvent
interface.
Properties available on the RowDragEvent<TData = any, TContext = any, T extends AgEventType = any>
interface.
The row node getting dragged. Also the node that started the drag when multi-row dragging. |
The list of nodes being dragged. |
The underlying mouse move event associated with the drag. |
The eventPath persists the event.composedPath() result for access within AG Grid event handlers. |
Direction of the drag, either 'up' , 'down' or null (if mouse is moving horizontally and not vertically). |
The row index the mouse is dragging over or -1 if over no row. |
The row node the mouse is dragging over or undefined if over no row. |
The vertical pixel location the mouse is over, with 0 meaning the top of the first row. This can be compared to the rowNode.rowHeight and rowNode.rowTop to work out the mouse position relative to rows. The provided attributes overIndex and overNode means the y property is mostly redundant. The y property can be handy if you want more information such as 'how close is the mouse to the top or bottom of the row?'
|
The grid api. |
Application context as set on gridOptions.context . |
Event identifier |
Example Events
The below example demonstrates unmanaged row dragging with no attempt by the application or the grid to re-order the rows - this is on purpose to demonstrate the grid will not attempt to re-order rows unless you set the rowDragManaged
property. The example also demonstrates all the events that are fired.
From the example the following can be noted:
The first column has
rowDrag=true
which results in a draggable area included in the cell.The grid has not set
rowDragManaged
which results in the grid not reordering rows as they are dragged.All of the drag events are listened for and when one is received, it is printed to the console. To best see this, open the example in a new tab and open the developer console.
Because
rowDragManaged
is not set, the row dragging is left enabled even if sorting or filtering is applied. This is because your application should decide if dragging should be allowed or suppressed using thesuppressRowDrag
property.
Simple Unmanaged Example
The example below shows how to implement simple row dragging using unmanaged row dragging and events. The example behaves the same as the Managed Dragging example above, however the logic for moving the rows is in the application rather than the grid.
From the example the following can be noted:
- The property
suppressRowDrag=true
is set by the application depending on whether sorting or filtering is active. This is because the logic in the example doesn't cover these scenarios and wants to prevent row dragging when sorting or filtering is active.
The simple example doesn't add anything that managed dragging gives (the first example on this page). Things get interesting when we introduce complex scenarios such as row grouping or tree data, which are explained below.
Dragging Multiple Rows with unmanaged row dragging, the application is in control of what gets dragged, so it is possible to use the events to drag more than one row at a time, e.g. to move all selected rows in one go if using row selection.
Entire Row Dragging
When using row dragging it is also possible to reorder rows by clicking and dragging anywhere on the row without the need for a drag handle by enabling the rowDragEntireRow
grid option as shown below:
const [columnDefs, setColumnDefs] = useState([
{ field: 'country' },
{ field: 'year' },
{ field: 'sport' },
{ field: 'total' }
]);
// allows rows to be dragged without the need for drag handles
const rowDragEntireRow = true;
<AgGridReact
columnDefs={columnDefs}
rowDragEntireRow={rowDragEntireRow}
/>
The example below demonstrates entire row dragging with Multi-Row Dragging. Note the following:
- Reordering rows by clicking and dragging anywhere on a row is possible as
rowDragEntireRow
is enabled. - Multiple rows can be selected and dragged as
rowDragMultiRow
is also enabled withselection.mode = 'multiRow'
. - Row Drag Managed is being used, but it is not a requirement for
Entire Row Dragging
.
Cell Selection is not supported when rowDragEntireRow
is enabled.
Suppress Row Drag
You can hide the draggable area by setting the grid option suppressRowDrag = true
.
The example below is almost identical to the Managed Dragging example with the following differences:
- Button Suppress will hide the drag icons.
- Button Remove Suppress will un-hide the drag icons.
- Applying a sort or a filter to the grid will also suppress the drag icons.
Dragging & Row Grouping
Row Grouping in the grid allows grouping rows by a particular column. Dragging rows while grouping is possible when doing unmanaged row dragging. The application is responsible for updating the data based on the drag events fired by the grid.
The example below uses row dragging to place rows into groups. It does not try to order the rows within the group. For this reason, the logic works regardless of sorting or filtering.
The example below shows row dragging with Row Grouping where the following can be noted:
- The Athlete column has row drag enabled for non-group rows. This is achieved using the function variant of the
rowDrag
property. - The grid has not set the
rowDragManaged
property which results in unmanaged row dragging. - The example does not re-order the rows. Instead the example demonstrates putting the rows into groups. If you drag a row, you can place it in a different parent group.
- The example listens to the event
onRowDragMove
and changes the group a row belongs to while the drag is happening (which is different to the next Tree Data example which waits until the drag is complete). It is the choice of your application whether it wants to move rows in real time during the drag, or wait until the drag action is complete. - The application can still move rows to groups even if ordering or sorting is applied. For this reason, the application does not suppress row dragging if sorting or filtering is applied.
Row Dragging & Tree Data
Tree Data in the grid allows providing data to the grid in parent / child relationships, similar to that required for a file browser. Dragging rows with tree data is possible when doing unmanaged row dragging. The application is responsible for updating the data based on the drag events fired by the grid.
Example Tree Data
The example below shows Tree Data and row dragging where the following can be noted:
The auto-group column has row drag
true
for all rows.The example registers for
onRowDragEnd
events and rearranges the rows when the drag completes.The application does NOT rearrange the rows as the drag is happening. Instead it waits for the
onRowDragEnd
event before updating the data.The expanded/contracted state of a folder and all of its child folders is preserved when the folder is moved to a new parent.
Example Highlighted Tree Data
The example above works, however it is not intuitive as the user is given no visual hint what folder will be the destination folder. The example below continues with the example above by providing hints to the user while the drag is in progress. From the example the following can be observed:
The example registers for
onRowDragMove
events and works out what folder the mouse is over as the drag is happening.While the row is dragging, the application highlights the folder that is currently selected as the destination folder (called
potentialParent
in the example code).The application does NOT rearrange the rows as the drag is happening. As with the previous example, it waits for the
onRowDragEnd
event before updating the data.The example uses Cell Class Rules to highlight the destination folder. The example adds a CSS class
hover-over
to all the cells of the destination folder.The example uses Refresh Cells to get the grid to execute the Cell Class Rules again over the destination folder when the destination folder changes.
Other Row Models
Unmanaged row dragging will work with any of the row models Infinite, Server-Side and Viewport. With unmanaged dragging, the implementation of what happens when a particular drag happens is up to your application.
Customisation
There are some options that can be used to customise the Row Drag experience, so it has a better integration with your application.
Custom Row Drag Text
When a row drag starts, a "floating" DOM element is created to indicate which row is being dragged. By default, this DOM element will contain the same value as the cell that started the row drag. It's possible to override that text by using the gridOptions.rowDragText
callback.
A callback that should return a string to be displayed by the rowDragComp while dragging a row.
If this callback is not set, the current cell value will be used.
If the rowDragText callback is set in the ColDef it will take precedence over this, except when
rowDragEntireRow=true . |
const [columnDefs, setColumnDefs] = useState([
{
field: 'athlete',
rowDrag: true
}, {
field: 'country'
}
]);
const rowDragText = (params, dragItemCount) => {
return (
dragItemCount > 1
? (dragItemCount + ' items')
: params.defaultTextValue + ' is'
) + ' being dragged...';
};
<AgGridReact
columnDefs={columnDefs}
rowDragText={rowDragText}
/>
The example below shows dragging with custom text. The following can be noted:
- When you drag a row of the year 2012, the
rowDragText
callback will add (London Olympics) to the floating drag element.
Custom Row Drag Text with Multiple Draggers
If the grid has more than one column set with rowDrag=true
, the rowDragText
callback can be set in the colDef
.
const [columnDefs, setColumnDefs] = useState([
{
field: 'athlete',
rowDrag: true
}, {
field: 'country',
rowDrag: true,
rowDragText: (params, dragItemCount) => {
const suffix = dragItemCount == 1 ? 'country' : 'countries';
return `Dragging ${dragItemCount} ${suffix}`;
}
}
]);
const rowDragText = (params, dragItemCount) => {
return (
dragItemCount > 1
? (dragItemCount + ' items')
: params.defaultTextValue + ' is'
) + ' being dragged...';
};
<AgGridReact
columnDefs={columnDefs}
rowDragText={rowDragText}
/>
The example below shows dragging with custom text and multiple column draggers. The following can be noted:
When you drag a row with a year of 2012 by the country row dragger, the
rowDragText
callback will add (London Olympics) to the floating drag element.When you drag the row by the athlete row dragger, the
rowDragText
callback in thegridOptions
will be overridden by the one in thecolDef
and will display the number of athletes selected.
Row Dragger inside Custom Cell Renderers
Due to the complexity of some applications, it could be handy to render the Row Drag Component inside of a Custom Cell Renderer. This can be achieved, by using the registerRowDragger
method in the ICellRendererParams as follows:
// your custom cell renderer code
// this will hold the reference to the element you want to act as row dragger.
const myRef = useRef(null);
useEffect(() => {
props.registerRowDragger(myRef.current!);
});
When using registerRowDragger
you should not set the property rowDrag=true
in the Column Definition. Doing that will cause the cell to have two row draggers.
The example below shows a custom cell renderer, with using the registerRowDragger
callback to render the Row Dragger inside itself.
- When you hover the cells, an arrow will appear, and this arrow can be used to drag the rows.
Full Width Row Dragging
It is possible to drag Full Width Rows by registering a Custom Row Dragger.
Note the following:
- Only the Full Width Rows are draggable.
Row Dragger with Custom Start Drag Pixels
By default, the drag event only starts after the Row Drag Element has been dragged by 4px
, but sometimes it might be useful to start the drag with a different drag threshold, for example, start dragging as soon as the mousedown
event happens (dragged by 0px
). For that reason, the registerRowDragger
takes a second parameter to specify the number of pixels that will start the drag event.
Note the following:
- The drag event starts as soon as
mousedown
is fired.
Custom Drag And Drop Image
The drag and drop image can be customised via the grid properties dragAndDropImageComponent
and dragAndDropImageComponentParams
.
const CustomDragAndDropImage = (props: CustomDragAndDropImageProps) => {
return <div>{props.label}</div>;
};
The following props are passed to the Custom Component (CustomDragAndDropImageProps
interface).
CustomDragAndDropImageProps
The label provided by the grid about the item being dragged. |
The name of the icon provided by the grid about the current drop target. |
True if the grid is attempting to scroll horizontally while dragging. |
DragSource |
The grid api. |
Application context as set on gridOptions.context . |
Custom Params
On top of the parameters provided by the grid, you can also provide your own parameters. This is useful if you want to allow configuring the component. For example, you might have parts of the grid that you want to highlight with a different colour.
colDef = {
dragAndDropImageComponent: MyDragAndDropImageComponent;
dragAndDropImageComponentParams : {
accentColour: 'SlateGray'
}
}