Table

A secondary encapsulation of the element-plus table component. Simplifies table configuration.

Table only owns the presentation contract. It does not handle request, pagination, or page workflow concerns. Cell rendering priority is: column slot > formatter > emptyValue > nullishText (default '--', triggers only on null / undefined) > default field value.

The exported TableColumn type is an Ez-UI maintained public boundary. It does not directly expose Element Plus internal column context types; apart from the documented extension fields, other public column props continue to be forwarded to el-table-column.

Default Nullish Fallback

For data columns that do not declare a formatter or emptyValue, Ez-UI auto-injects a default formatter: when the cell's raw value is null or undefined, it renders as nullishText (default '--'); empty string '' is NOT treated as nullish and is passed through unchanged. The priority is always: column-level formatter > column-level emptyValue > auto-injected nullishText fallback.

Basic Usage

Tree Table

Functional Table

Nullish Fallback

Table Attributes

Attribute	Description	Type	Extensible	Default Value
data	Table data	Array	No	[]
columns	Column configuration	TableColumn[]	Yes	[]
height	Height of the table. Defaults to automatic height, and the table's height is controlled by external styles.	enum stringnumber	No	—
max-height	Maximum height of the table	enum stringnumber	No	—
stripe	Whether to use striped rows	boolean	No	false
border	Whether to have vertical borders	boolean	No	true
size	Size of the Table	enum ''largedefaultsmall'	No	—
fit	Whether the column width should stretch to fit	boolean	No	true
show-header	Whether to show the table header	boolean	No	true
highlight-current-row	Whether to highlight the current row	boolean	No	false
current-row-key	Key of the current row, read-only	enum stringnumber	No	—
row-class-name	Callback method for row className, or use a string to set a fixed className for all rows.	enum Functionstring	No	—
row-style	Callback method for row style, or use a fixed Object to set the same style for all rows.	enum FunctionCSSProperties	No	—
cell-class-name	Callback method for cell className, or use a string to set a fixed className for all cells.	enum Functionstring	No	—
cell-style	Callback method for cell style, or use a fixed Object to set the same style for all cells.	enum FunctionCSSProperties	No	—
header-row-class-name	Callback method for header row className, or use a string to set a fixed className for all header rows.	enum Functionstring	No	—
header-row-style	Callback method for header row style, or use a fixed Object to set the same style for all header rows.	enum FunctionCSSProperties	No	—
header-cell-class-name	Callback method for header cell className, or use a string to set a fixed className for all header cells.	enum Functionstring	No	—
header-cell-style	Callback method for header cell style, or use a fixed Object to set the same style for all header cells.	enum FunctionCSSProperties	No	—
row-key	Key for row data to optimize Table rendering; required when using reserve-selection functionality or displaying tree data.	enum Functionstring	No	id
empty-text	Text content to display when there is no data; can also be set through a slot.	string	No	No Data
default-expand-all	Whether to expand all rows by default, effective when the Table contains expandable rows or is a tree table.	boolean	No	false
expand-row-keys	Set the currently expanded rows using this property; needs row-key to be set, this property is an array of expanded row keys.	Array	No	—
default-sort	Default sorting column's prop and order. The prop attribute specifies the default sorting column, order specifies the default sorting order.	object	No	prop set, order default ascending
tooltip-effect	Effect of the overflow tooltip	enum darklight	No	dark
tooltip-options	Options for overflow tooltip, refer to the tooltip component below.	object	No	object
show-summary	Whether to show a summary row at the bottom of the table	boolean	No	false
sum-text	Text to display in the first column of the summary row	string	No	Sum
summary-method	Custom summary calculation method	Function	No	—
span-method	Method to merge rows or columns	Function	No	—
select-on-indeterminate	In a multi-select table, the behavior when only some rows are selected and the header checkbox is clicked. If true, select all rows; if false, deselect all rows.	boolean	No	true
indent	Indentation of tree nodes when displaying tree data	number	No	16
lazy	Whether to lazily load child node data	boolean	No	false
load	Function to load child node data, effective when lazy is true.	Function	No	—
tree-props	Configuration options for rendering nested data	object { hasChildren?: string, children?: string }	No	object { hasChildren: "hasChildren", children: "children" }
table-layout	Set the layout method for table cells, rows, and columns	enum fixedauto	No	fixed
scrollbar-always-on	Always show scrollbars	boolean	No	false
show-overflow-tooltip	Whether to hide extra content and use Tooltip to show them on hover. This affects the display of all columns.	enum booleanobject	No	—
flexible	Ensure the minimum size of the main axis to avoid overflow of content.	boolean	No	false
nullish-text	Default placeholder for nullish cell values; only applies to data columns without formatter / emptyValue. Triggers on null / undefined; empty string '' passes through.	string	Yes	'--'

TableColumn Attributes

Attribute	Description	Type	Extensible	Default Value
type	Column type. If set to selection, shows a checkbox; if set to index, shows the row index (starting from 1); if set to expand, shows an expandable button.	enum defaultselectionindexexpand	No	default
index	If type=index is set, you can use the index property to customize the index.	enum numberFunction	No	—
label	Display title	string	No	—
column-key	Column key, required to identify which column's filter conditions are being used for filter-change events.	string	No	—
prop	Field name corresponding to the column's content, can also use the property attribute.	string	No	—
width	Width of the column	enum stringnumber	No	''
min-width	Minimum width of the column. Unlike width, min-width allocates remaining width proportionally to columns with min-width set.	enum stringnumber	No	''
fixed	Whether the column is fixed to the left or right. True indicates fixed to the left.	enum 'left''right'boolean	No	false
render-header	Function for rendering the column header label area	Function	No	—
sortable	Whether the column can be sorted. If set to 'custom', remote sorting is needed and the Table's sort-change event needs to be listened to.	enum 'custom'boolean	No	false
sort-mode	Sorting mode. local keeps Element Plus local sorting, remote automatically normalizes sortable to custom	enum localremote	Yes	local
sort-field	Remote sorting field name. Defaults to the current column prop	string	Yes	—
sort-method	Specify which property the data is sorted by, valid only when sortable is true. Should return a Number like Array.sort.	Function	No	—
sort-by	Specify which property the data is sorted by, valid only when sortable is true and no sort-method is set. If sort-by is an array, it sorts by the first property, then the second if the first is the same.	enum Functionstringobject	No	—
sort-orders	the order of the sorting strategies used when sorting the data, works when sortable is true. Accepts an array, as the user clicks on the header, the column is sorted in order of the elements in the array	object	No	['ascending', 'descending', null]
resizable	whether column width can be resized, works when border of el-table is true	boolean	No	true
formatter	Function that formats cell content. Effective when no same-name column slot is provided	Function (row: any, column: any, cellValue: any, index: number) => VNode | string	No	—
empty-value	Fallback text when the current cell value is empty. Applied after formatter and before the default field value	string	Yes	—
show-overflow-tooltip	whether to hide extra content and show them in a tooltip when hovering on the cell	enum booleanobject	No	undefined
align	alignment	enum leftcenterright	No	center
header-align	alignment of the table header. If omitted, the value of the above align attribute will be applied	enum leftcenterright	No	center
class-name	class name of cells in the column	string	No	—
label-class-name	class name of the label of this column	string	No	—
hidden	Whether to hide the column. true means hidden	boolean	Yes	false
selectable	function that determines if a certain row can be selected, works when type is 'selection'	Function	No	—
reserve-selection	whether to reserve selection after data refreshing, works when type is 'selection'. Note that row-key is required for this to work	boolean	No	false
filters	an array of data filtering options. For each element in this array, text and value are required	object	No	—
filter-placement	placement for the filter dropdown	enum toptop-starttop-endbottombottom-startbottom-endleftleft-startleft-endrightright-startright-end	No	—
filter-class-name	className for the filter dropdown	string	No	—
filter-multiple	whether data filtering supports multiple options	boolean	No	true
filter-method	data filtering method. If filter-multiple is on, this method will be called multiple times for each row, and a row will display if one of the calls returns true	function	No	—
filtered-value	filter value for selected data, might be useful when table header is rendered with render-header	object	No	—

Notes: Ez-UI provides default values of align: 'center' and resizable: true; showOverflowTooltip is disabled by default for the last visible data column, which is commonly used as an operation column.

Slots

Name	Description	Type
${prop}	Slot for data columns, suitable for complex data processing	object { row: any, column: any, $index: number }
header-${prop}	General header slot, associated through the prop of columns item	object { column: any, $index: number }
append	Content inserted after the last row of the table	-
empty	Custom content when data is empty	-

Events

Name	Description	Type	Expand
select	Event triggered when the user manually checks a data row's checkbox	Function <T = any>(selection: T[], row: T) => void	No
select-all	Event triggered when the user manually checks the "select all" checkbox	Function (visible) => void	No
selection-change	Event triggered when the selected items change	Function (newSelection: any[]) => void	No
cell-mouse-enter	Event triggered when hovering enters a cell	Function (row: any, column: any, cell: HTMLTableCellElement, event: Event) => void	No
cell-mouse-leave	Event triggered when hovering leaves a cell	Function (row: any, column: any, cell: HTMLTableCellElement, event: Event) => void	No
cell-click	Event triggered when a cell is clicked	Function (row: any, column: any, cell: HTMLTableCellElement, event: Event) => void	No
cell-dblclick	Event triggered when a cell is double-clicked	Function (row: any, column: any, cell: HTMLTableCellElement, event: Event) => void	No
cell-contextmenu	Event triggered when a cell is right-clicked	Function (row: any, column: any, cell: HTMLTableCellElement, event: Event) => void	No
row-click	Event triggered when a row is clicked	Function (row: any, column: any, event: Event) => void	No
row-contextmenu	Event triggered when a row is right-clicked	Function (row: any, column: any, event: Event) => void	No
row-dblclick	Event triggered when a row is double-clicked	Function (row: any, column: any, event: Event) => void	No
header-click	Event triggered when a column header is clicked	Function (column: any, event: Event) => void	No
header-contextmenu	Event triggered when a column header is right-clicked	Function (column: any, event: Event) => void	No
sort-change	Event triggered when the table's sorting conditions change	Function (data: {column: any, prop: string, order: any }) => void	No
filter-change	Key of the column; if you need to use the filter-change event, this property identifies which column's filter condition	Function (newFilters: any) => void	No
current-change	Event triggered when the table's current row changes. If you want to highlight the current row, enable the table's highlight-current-row property	Function (currentRow: any, oldCurrentRow: any) => void	No
header-dragend	Event triggered when the width of a column is changed by dragging the column header	Function (newWidth: number, oldWidth: number, column: any, event: MouseEvent) => void	No
expand-change	Event triggered when a user expands or collapses a row (when expanding rows, the second parameter of the callback is expandedRows; for tree tables, the second parameter is expanded)	Function (row: any, expandedRows: any[]) => void & (row: any, expanded: boolean) => void	No

Table Exposes

Method Name	Description	Type
getTableRef	Get el-table instance (escape hatch)	Function () => TableInstance
clearSelection	Clear user's selection	Function () => void
toggleRowSelection	Toggle selection state of a specific row	Function (row: any, selected?: boolean) => void
toggleAllSelection	Toggle between select all and deselect all	Function () => void
toggleRowExpansion	Toggle expansion state of a specific row	Function (row: any, expanded?: boolean) => void
setCurrentRow	Set a row as the selected row	Function (row: any) => void
clearSort	Clear the sorting condition	Function () => void
clearFilter	Clear filter conditions for specified columns	Function (columnKey?: string | string[]) => void
doLayout	Re-layout the Table	Function () => void
sort	Manually sort the table	Function (prop: string, order: 'ascending' | 'descending' | null) => void

💡 The methods above can be called directly on the EzTable instance. For other el-table methods (e.g., scrollTo, getSelectionRows), use getTableRef() to access the underlying instance.