React Data GridRow Dragging

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

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.

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:

1. rowDragEnter fired once - The drag has started.
2. rowDragMove fired multiple times - The mouse is dragging over the rows.
3. 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.

Each of the four row drag events extend the RowDragEvent interface.

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 the suppressRowDrag 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.

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 with rowSelection.mode = 'multiRow'.
• Row Drag Managed is being used, but it is not a requirement for Entire Row Dragging.

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.

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 the gridOptions will be overridden by the one in the colDef 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!);
});

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.

const CustomDragAndDropImage = (props: CustomDragAndDropImageProps) => {
    return <div>{props.label}</div>;
};

colDef = {
    dragAndDropImageComponent: MyDragAndDropImageComponent;
    dragAndDropImageComponentParams : {
        accentColour: 'SlateGray'
    }
}