React TreeList API
The TreeList is a UI component that represents data from a local or remote source in the form of a multi-column tree view. This UI component offers such features as sorting, filtering, editing, selection, etc.
Props
An object defining configuration properties for the TreeList UI component.
| Name | Description |
|---|---|
| accessKey | Specifies the shortcut key that sets focus on the UI component. |
| activeStateEnabled | Specifies whether or not the UI component changes its state when interacting with a user. |
| allowColumnReordering | Specifies whether a user can reorder columns. |
| allowColumnResizing | Specifies whether a user can resize columns. |
| autoExpandAll | Specifies whether all rows are expanded initially. |
| autoNavigateToFocusedRow | Automatically scrolls to the focused row when the focusedRowKey is changed. |
| cacheEnabled | Specifies whether data should be cached. |
| cellHintEnabled | Enables a hint that appears when a user hovers the mouse pointer over a cell with truncated content. |
| columnAutoWidth | Specifies whether columns should adjust their widths to the content. |
| columnChooser | Configures the column chooser. |
| columnFixing | Configures column fixing. |
| columnHidingEnabled | Specifies whether the UI component should hide columns to adapt to the screen or container size. Ignored if allowColumnResizing is true and columnResizingMode is "widget". |
| columnMinWidth | Specifies the minimum width of columns. |
| columnResizingMode | Specifies how the UI component resizes columns. Applies only if allowColumnResizing is true. |
| columns | Configures columns. |
| columnWidth | Specifies the width for all data columns. Has a lower priority than the column.width property. |
| customizeColumns | Customizes columns after they are created. |
| dataSource | Binds the UI component to data. |
| dataStructure | Notifies the UI component of the used data structure. |
| dateSerializationFormat | Specifies the format in which date-time values should be sent to the server. |
| disabled | Specifies whether the UI component responds to user interaction. |
| editing | Configures editing. |
| elementAttr | Specifies the global attributes to be attached to the UI component's container element. |
| errorRowEnabled | Indicates whether to show the error row. |
| expandedRowKeys | Specifies keys of the initially expanded rows. |
| expandNodesOnFiltering | Specifies whether nodes appear expanded or collapsed after filtering is applied. |
| filterBuilder | Configures the integrated filter builder. |
| filterBuilderPopup | Configures the popup in which the integrated filter builder is shown. |
| filterMode | Specifies whether filter and search results should include matching rows only, matching rows with ancestors, or matching rows with ancestors and descendants (full branch). |
| filterPanel | Configures the filter panel. |
| filterRow | Configures the filter row. |
| filterSyncEnabled | Specifies whether to synchronize the filter row, header filter, and filter builder. The synchronized filter expression is stored in the filterValue property. |
| filterValue | Specifies a filter expression. |
| focusedColumnIndex | The index of the column that contains the focused data cell. This index is taken from the columns array. |
| focusedRowEnabled | Specifies whether the focused row feature is enabled. |
| focusedRowIndex | Specifies or indicates the focused data row's index. |
| focusedRowKey | Specifies initially or currently focused grid row's key. |
| focusStateEnabled | Specifies whether the UI component can be focused using keyboard navigation. |
| hasItemsExpr | Specifies which data field defines whether the node has children. |
| headerFilter | Configures the header filter feature. |
| height | Specifies the UI component's height. |
| highlightChanges | Specifies whether to highlight rows and cells with edited data. repaintChangesOnly should be true. |
| hint | Specifies text for a hint that appears when a user pauses on the UI component. |
| hoverStateEnabled | Specifies whether to highlight rows when a user moves the mouse pointer over them. |
| itemsExpr | Specifies which data field contains nested items. Set this property when your data has a hierarchical structure. |
| keyboardNavigation | Configures keyboard navigation. |
| keyExpr | Specifies the key property (or properties) that provide(s) key values to access data items. Each key value must be unique. |
| loadPanel | Configures the load panel. |
| noDataText | Specifies a text string shown when the TreeList does not display any data. |
| onAdaptiveDetailRowPreparing | A function that is executed before an adaptive detail row is rendered. |
| onCellClick | A function that is executed when a cell is clicked or tapped. Executed before onRowClick. |
| onCellDblClick | A function that is executed when a cell is double-clicked or double-tapped. Executed before onRowDblClick. |
| onCellHoverChanged | A function that is executed after the pointer enters or leaves a cell. |
| onCellPrepared | A function that is executed after a grid cell is created. |
| onContentReady | A function that is executed when the UI component's content is ready and each time the content is changed. |
| onContextMenuPreparing | A function that is executed before the context menu is rendered. |
| onDataErrorOccurred | A function that is executed when an error occurs in the data source. |
| onDisposing | A function that is executed before the UI component is disposed of. |
| onEditCanceled | A function that is executed after row changes are discarded. |
| onEditCanceling | A function that is executed when the edit operation is canceled, but row changes are not yet discarded. |
| onEditingStart | A function that is executed before a cell or row switches to the editing state. |
| onEditorPrepared | A function that is executed after an editor is created. Not executed for cells with an editCellTemplate. |
| onEditorPreparing | A function used to customize a cell's editor. Not executed for cells with an editCellTemplate. |
| onFocusedCellChanged | A function that is executed after the focused cell changes. Applies only to cells in data rows. |
| onFocusedCellChanging | A function that is executed before the focused cell changes. Applies only to cells in data rows. |
| onFocusedRowChanged | A function that executed when the focused row changes. Applies only to data rows. focusedRowEnabled should be true. |
| onFocusedRowChanging | A function that is executed before the focused row changes. Applies only to data rows. focusedRowEnabled should be true. |
| onInitialized | A function used in JavaScript frameworks to save the UI component instance. |
| onInitNewRow | A function that is executed before a new row is added to the UI component. |
| onKeyDown | A function that is executed when the UI component is in focus and a key has been pressed down. |
| onNodesInitialized | A function that is executed after the loaded nodes are initialized. |
| onOptionChanged | A function that is executed after a UI component property is changed. |
| onRowClick | A function that is executed when a grid row is clicked or tapped. |
| onRowCollapsed | A function that is executed after a row is collapsed. |
| onRowCollapsing | A function that is executed before a row is collapsed. |
| onRowDblClick | A function that is executed when a row is double-clicked or double-tapped. Executed after onCellDblClick. |
| onRowExpanded | A function that is executed after a row is expanded. |
| onRowExpanding | A function that is executed before a row is expanded. |
| onRowInserted | A function that is executed after a new row has been inserted into the data source. |
| onRowInserting | A function that is executed before a new row is inserted into the data source. |
| onRowPrepared | A function that is executed after a row is created. |
| onRowRemoved | A function that is executed after a row has been removed from the data source. |
| onRowRemoving | A function that is executed before a row is removed from the data source. |
| onRowUpdated | A function that is executed after a row has been updated in the data source. |
| onRowUpdating | A function that is executed before a row is updated in the data source. |
| onRowValidating | A function that is executed after cells in a row are validated against validation rules. |
| onSaved | A function that is executed after row changes are saved. |
| onSaving | A function that is executed before pending row changes are saved. |
| onSelectionChanged | A function that is executed after selecting a row or clearing its selection. |
| onToolbarPreparing | A function that is executed before the toolbar is created. |
| pager | Configures the pager. |
| paging | Configures paging. |
| parentIdExpr | Specifies which data field provides parent keys. |
| remoteOperations | Notifies the TreeList of the server's data processing operations. Applies only if data has a plain structure. |
| renderAsync | Specifies whether to render the filter row, command columns, and columns with showEditorAlways set to true after other elements. |
| repaintChangesOnly | Specifies whether to repaint only those cells whose data changed. |
| rootValue | Specifies the root node's identifier. Applies if dataStructure is "plain". |
| rowAlternationEnabled | Specifies whether rows should be shaded differently. |
| rowDragging | Configures row reordering using drag and drop gestures. |
| rtlEnabled | Switches the UI component to a right-to-left representation. |
| scrolling | Configures scrolling. |
| searchPanel | Configures the search panel. |
| selectedRowKeys | Allows you to select rows or determine which rows are selected. |
| selection | Configures runtime selection. |
| showBorders | Specifies whether the outer borders of the UI component are visible. |
| showColumnHeaders | Specifies whether column headers are visible. |
| showColumnLines | Specifies whether vertical lines that separate one column from another are visible. |
| showRowLines | Specifies whether horizontal lines that separate one row from another are visible. |
| sorting | Configures runtime sorting. |
| stateStoring | Configures state storing. |
| tabIndex | Specifies the number of the element when the Tab key is used for navigating. |
| twoWayBindingEnabled | Specifies whether to enable two-way data binding. |
| visible | Specifies whether the UI component is visible. |
| width | Specifies the UI component's width. |
| wordWrapEnabled | Specifies whether text that does not fit into a column should be wrapped. |
Methods
This section describes methods that you can use to manipulate the TreeList UI component in code.
| Name | Description |
|---|---|
| addColumn(columnOptions) | Adds a new column. |
| addRow() | Adds an empty data row to the highest hierarchical level and switches it to the editing state. |
| addRow(parentId) | Adds an empty data row to a specified parent row. |
| beginCustomLoading(messageText) | Shows the load panel. |
| beginUpdate() | Prevents the UI component from refreshing until the endUpdate() method is called. |
| byKey(key) | Gets a data object with a specific key. |
| cancelEditData() | Discards changes that a user made to data. |
| cellValue(rowIndex, dataField) | Gets the value of a cell with a specific row index and a data field, column caption or name. |
| cellValue(rowIndex, dataField, value) | Sets a new value to a cell with a specific row index and a data field, column caption or name. |
| cellValue(rowIndex, visibleColumnIndex) | Gets the value of a cell with specific row and column indexes. |
| cellValue(rowIndex, visibleColumnIndex, value) | Sets a new value to a cell with specific row and column indexes. |
| clearFilter() | Clears all filters applied to UI component rows. |
| clearFilter(filterName) | Clears all row filters of a specific type. |
| clearSelection() | Clears selection of all rows on all pages. |
| clearSorting() | Clears sorting settings of all columns at once. |
| closeEditCell() | Switches the cell being edited back to the normal state. Takes effect only if editing.mode is batch or cell and showEditorAlways is false. |
| collapseAdaptiveDetailRow() | Collapses the currently expanded adaptive detail row (if there is one). |
| collapseRow(key) | Collapses a row with a specific key. |
| columnCount() | Gets the data column count. Includes visible and hidden columns, excludes command columns. |
| columnOption(id) | Gets all properties of a column with a specific identifier. |
| columnOption(id, optionName) | Gets the value of a single column property. |
| columnOption(id, optionName, optionValue) | Updates the value of a single column property. |
| columnOption(id, options) | Updates the values of several column properties. |
| defaultOptions(rule) | Specifies the device-dependent default configuration properties for this component. |
| deleteColumn(id) | Removes a column. |
| deleteRow(rowIndex) | Removes a row with a specific index. |
| deselectAll() | Clears the selection of all rows on all pages or the currently rendered page only. |
| deselectRows(keys) | Cancels the selection of rows with specific keys. |
| dispose() | Disposes of all the resources allocated to the TreeList instance. |
| editCell(rowIndex, dataField) | Switches a cell with a specific row index and a data field to the editing state. Takes effect only if the editing mode is "batch" or "cell". |
| editCell(rowIndex, visibleColumnIndex) | Switches a cell with specific row and column indexes to the editing state. Takes effect only if the editing mode is "batch" or "cell". |
| editRow(rowIndex) | Switches a row with a specific index to the editing state. Takes effect only if the editing mode is "row", "popup" or "form". |
| element() | Gets the root UI component element. |
| endCustomLoading() | Hides the load panel. |
| endUpdate() | Refreshes the UI component after a call of the beginUpdate() method. |
| expandAdaptiveDetailRow(key) | Expands an adaptive detail row. |
| expandRow(key) | Expands a row with a specific key. |
| filter() | Gets a filter expression applied to the UI component's data source using the filter(filterExpr) method and the DataSource's filter property. |
| filter(filterExpr) | Applies a filter to the dataSource. |
| focus() | Sets focus on the UI component. |
| focus(element) | Sets focus on a specific cell. |
| forEachNode(callback) | Performs a pre-order tree traversal, executing a function on each visited node. Starts traversing from the top level nodes. |
| forEachNode(nodes, callback) | Performs a pre-order tree traversal, executing a function on each visited node. Starts traversing from the specified nodes. |
| getCellElement(rowIndex, dataField) | Gets a cell with a specific row index and a data field, column caption or name. |
| getCellElement(rowIndex, visibleColumnIndex) | Gets a cell with specific row and column indexes. |
| getCombinedFilter() | Gets the total filter that combines all the filters applied. |
| getCombinedFilter(returnDataField) | Gets the total filter that combines all the filters applied. |
| getDataSource() | Gets the DataSource instance. |
| getInstance(element) | Gets the instance of a UI component found using its DOM node. |
| getKeyByRowIndex(rowIndex) | Gets the key of a row with a specific index. |
| getNodeByKey(key) | Gets a node with a specific key. |
| getRootNode() | Gets the root node. |
| getRowElement(rowIndex) | Gets the container of a row with a specific index. |
| getRowIndexByKey(key) | Gets the index of a row with a specific key. |
| getScrollable() | Gets the instance of the UI component's scrollable part. |
| getSelectedRowKeys() | Gets the keys of the rows selected explicitly via the API or via a click or tap. |
| getSelectedRowKeys(mode) | Gets the selected rows' keys. |
| getSelectedRowsData() | Gets the data objects of the rows selected explicitly via the API or via a click or tap. |
| getSelectedRowsData(mode) | Gets the selected rows' data objects. |
| getVisibleColumnIndex(id) | Gets the index of a visible column. |
| getVisibleColumns() | Gets all visible columns. |
| getVisibleColumns(headerLevel) | Gets all visible columns at a specific hierarchical level of column headers. Use it to access banded columns. |
| getVisibleRows() | Gets currently rendered rows. |
| hasEditData() | Checks whether the UI component has unsaved changes. |
| hideColumnChooser() | Hides the column chooser. |
| instance() | Gets the UI component's instance. Use it to access other methods of the UI component. |
| isAdaptiveDetailRowExpanded(key) | Checks whether an adaptive detail row is expanded or collapsed. |
| isRowExpanded(key) | Checks whether a row is expanded or collapsed. |
| isRowFocused(key) | Checks whether a row with a specific key is focused. |
| isRowSelected(key) | Checks whether a row with a specific key is selected. |
| keyOf(obj) | Gets a data object's key. |
| loadDescendants() | Loads all root node descendants (all data items). Takes effect only if data has the plain structure and remoteOperations | filtering is true. |
| loadDescendants(keys) | Loads a specific node's descendants. Takes effect only if data has the plain structure and remoteOperations | filtering is true. |
| loadDescendants(keys, childrenOnly) | Loads all or only direct descendants of specific nodes. Takes effect only if data has the plain structure and remoteOperations | filtering is true. |
| navigateToRow(key) | Navigates to a row with the specified key. |
| off(eventName) | Detaches all event handlers from a single event. |
| off(eventName, eventHandler) | Detaches a particular event handler from a single event. |
| on(eventName, eventHandler) | Subscribes to an event. |
| on(events) | Subscribes to events. |
| option() | Gets all UI component properties. |
| option(optionName) | Gets the value of a single property. |
| option(optionName, optionValue) | Updates the value of a single property. |
| option(options) | Updates the values of several properties. |
| pageCount() | Gets the total page count. |
| pageIndex() | Gets the current page index. |
| pageIndex(newIndex) | Switches the UI component to a specific page using a zero-based index. |
| pageSize() | Gets the current page size. |
| pageSize(value) | Sets the page size. |
| refresh() | Reloads data and repaints data rows. |
| refresh(changesOnly) | Reloads data and repaints all or only updated data rows. |
| repaint() | Repaints the UI component without reloading data. Call it to update the UI component's markup. |
| repaintRows(rowIndexes) | Repaints specific rows. |
| resetOption(optionName) | Resets a property to its default value. |
| saveEditData() | Saves changes that a user made to data. |
| searchByText(text) | Seeks a search string in the columns whose allowSearch property is true. |
| selectAll() | Selects all rows. |
| selectRows(keys, preserve) | Selects rows with specific keys. |
| selectRowsByIndexes(indexes) | Selects rows with specific indexes. |
| showColumnChooser() | Shows the column chooser. |
| state() | Gets the current UI component state. |
| state(state) | Sets the UI component state. |
| undeleteRow(rowIndex) | Recovers a row deleted in batch editing mode. |
| updateDimensions() | Updates the UI component's content after resizing. |
Events
This section describes events raised by this UI component.
| Name | Description |
|---|---|
| adaptiveDetailRowPreparing | Raised before an adaptive detail row is rendered. |
| cellClick | Raised when a cell is clicked or tapped. |
| cellDblClick | Raised when a cell is double-clicked or double-tapped. |
| cellHoverChanged | Raised when the pointer enters or leaves a cell. |
| cellPrepared | Raised after a cell is created. |
| contentReady | Raised when the UI component's content is ready. |
| contextMenuPreparing | Raised before the context menu is rendered. |
| dataErrorOccurred | Raised when an error occurs in the data source. |
| disposing | Raised before the UI component is disposed of. |
| editCanceled | Raised after row changes are discarded. |
| editCanceling | Raised when the edit operation is canceled, but row changes are not yet discarded. |
| editingStart | Raised before a cell or row switches to the editing state. |
| editorPrepared | Raised after an editor is created. |
| editorPreparing | Raised before an editor is created. |
| focusedCellChanged | Raised after the focused cell changes. |
| focusedCellChanging | Raised before the focused cell changes. |
| focusedRowChanged | Raised after the focused row changes. Applies only when focusedRowEnabled is true. |
| focusedRowChanging | Raised before the focused row changes. Applies only when focusedRowEnabled is true. |
| initialized | Raised only once, after the UI component is initialized. |
| initNewRow | Raised before a new row is added to the UI component. |
| keyDown | Raised when the UI component is in focus and a key has been pressed down. |
| nodesInitialized | Raised after the loaded nodes are initialized. |
| optionChanged | Raised after a UI component property is changed. |
| rowClick | Raised when a row is clicked or tapped. |
| rowCollapsed | Raised after a row is collapsed. |
| rowCollapsing | Raised before a row is collapsed. |
| rowDblClick | Raised when a row is double-clicked or double-tapped. |
| rowExpanded | Raised after a row is expanded. |
| rowExpanding | Raised before a row is expanded. |
| rowInserted | Raised after a new row has been inserted into the data source. |
| rowInserting | Raised before a new row is inserted into the data source. |
| rowPrepared | Raised after a row is created. |
| rowRemoved | Raised after a row has been removed from the data source. |
| rowRemoving | Raised before a row is removed from the data source. |
| rowUpdated | Raised after a row has been updated in the data source. |
| rowUpdating | Raised before a row is updated in the data source. |
| rowValidating | Raised after cells in a row are validated against validation rules. |
| saved | Raised after row changes are saved. |
| saving | Raised before pending row changes are saved. |
| selectionChanged | Raised after selecting a row or clearing its selection. |
| toolbarPreparing | Raised before the toolbar is created. |
Node
A TreeList node's structure.
You can access nodes using the getRootNode() method and within some event handlers, for example, onNodesInitialized.
Row
A grid row.
A row is a visual representation of a node. You can access grid rows using the getVisibleRows() method and within some event handlers, for example, onCellClick, onCellPrepared, onEditorPreparing.
If you have technical questions, please create a support ticket in the DevExpress Support Center.