Skip to content

EnTableSortable ​

Preview ​

Props ​

NameDescriptionDefaultControl
headings

The column definitions, as SortableTableHeading objects.

array<SortableTableHeading>
unknowncomplex object
rows

An array of table data containing objects or array of strings or numbers, where each object/array is a row of table data. Objects are recommended for full feature use.

array
[…]complex object
groups

Optional grouped table data. When provided (non-empty), the table renders one <tbody> per group, each opening with a colspanned heading row (see the group-heading slot) followed by that group's rows. Each group is an object of shape { label, rows }; any extra properties are passed through to the group-heading slot. Grouped mode bypasses pagination (all groups render). The consumer is responsible for the order of the groups and the order of rows within each group.

array
[…]complex object
showGroupHeadings

Whether each group opens with a heading row. Turn it off when the group is already identifiable from the rows themselves — a column repeating the group name, or a totals row that names it — and the heading would just be a redundant band. A group select-all still forces the row to render, since that is where its checkbox lives.

boolean
true
groupSelectAll

Adds a select-all checkbox to each group's heading row that toggles only that group's rows within the shared selection. Requires enableBulkAction and a non-empty groups; ignored otherwise.

boolean
false
rowType

The type of each row of the table.

string
"object"
headerClass

CSS class that will be applied to all table headers.

string
""
wrapHeader

Whether or not the text in the table headers should be wrapped.

boolean
true
enableBulkAction

Enables checkboxes for bulk actions. NOTE: must have a v-model binding to an array to work properly. Do NOT also add a manual { key: 'bulk-action' } entry to headings — this prop prepends the bulk-action column automatically, so a manual one produces a duplicate checkbox column.

boolean
false
bulkActionProperty

Sets a property to pull from each selected item instead of the full object. e.g. set to 'Id' if you want to only include the Id from the selected objects.

string
null
totals

Optional grand totals rendered in a <tfoot> beneath every row. Keys are column keys; only the columns whose heading sets total: true are shown, so a totals object deserialized from the same model as a row (every property present, the non-aggregated ones null) renders correctly. The label cell is the footer slot.

object
nullcomplex object
fixedLayout

Switches the table to a fixed layout, which makes column widths absolute rather than negotiable.

Widths are honoured either way in the ordinary case — this only changes the two situations where the automatic layout overrules them. Content that cannot wrap narrower than its column (a long unbroken code) stops widening that column and overflows instead, and widths that together exceed the table stop being scaled down to fit, so the table overflows its container. Columns with no width share whatever is left.

Reach for it when a width has to hold exactly. It is not needed to make widths work.

boolean
false
perPage
number
0
currentPage
number
1
qaId

Id that can be set for automation selectors.

string
""
modelValue

Use v-model to bind to value of the bulk selected items.

unknown[]
unknown

Slots ​

${slot}-prelabel

Dynamically generated slot based on the key or slot property in the heading object; renders content before the heading label

<dynamic:name>

No description

Variables
NameTypeDescription
nameunknown—

body

render table rows

Variables
NameTypeDescription
rowsArray.<object>

The rows currently rendered: sorted, then paginated

headingsArray.<object>

Resolved column definitions in render order, matching the header

cell-contentsfunction

(value, headingIndex) formatter used by the default cells

${slot}

Dynamically generated slot based on the key or slot property in the heading object; used to modify the columns display value

Variables
NameTypeDescription
contentany

Default display value

rowobject

Full row object

row-indexnumber

Row index, does not take any pagination into account

heading-indexnumber

Column index

Events ​

update:model-value

No description

sort

No description

Methods ​

No methods defined.

Sorting ​

Sorting is driven entirely by the headings array — one SortableTableHeading per column. Each heading gets a clickable header that sorts on that column's key.

  • Only one column sorts at a time. Clicking a header makes it the active column and sorts ascending; clicking the active header again reverses it. Activating another column resets the previous one.
  • Set the initial sort with active: true on a heading, plus reversed: true to start descending. If more than one heading is marked active, the first one wins. With no active heading the rows render in the order they were passed.
  • The rows prop is never mutated. Each sort produces a new array and emits sort with the sorted rows. Re-assigning rows re-applies the current sort.
  • Reversing is a straight reversal of the ascending result, so values that sort last ascending (blanks, unranked values) lead when reversed.
  • Grouped tables sort inside each group. Pass groups and the group order and boundaries stay put — only the rows within each group are reordered.
  • Totals rows never sort. A group's totals row stays at the bottom of its group and the totals prop stays in the <tfoot>, whatever the sort. showGroupHeadings and totals are forwarded to EnTableBasic, which documents them.
  • The body slot receives the sorted, paged rows. It also passes the resolved headings and the cellContents formatter, so a hand-rendered <tbody> reflects the current sort and page.
  • Pagination sorts the full list first, then pages it, so sorting isn't limited to the visible page.

Sort types ​

The sortType on a heading picks the comparison. Note that sortIcon (numeric, alpha, or omitted for the default arrows) only changes the header icon — it has no effect on the sorting itself.

sortTypeComparesBlank / null values
omittedCase-insensitive string compare of the cell valueSort last
numericThe cell value with all non-numeric characters stripped, compared as a number — so "$120,000" sorts as 120000Treated as 0
dateThe cell value passed through new Date()Sort first
orderA rank you define per column — see Custom orderSort last
bulk-selectSelection order of the bulk-action checkboxes, selected rows first. Requires enableBulkAction; the header renders the select-all checkbox instead of a sort togglen/a
noneNothing — the column renders as plain, non-clickable header textn/a

For anything else, give the heading a compare function and it will be called with the two cell values, like the callback passed to Array.prototype.sort.

When a heading defines more than one of these, the order of precedence is: order → sortType (numeric, date, bulk-select) → compare → default string compare. So order overrides a compare function, but a numeric, date, or bulk-select sortType overrides order.

Custom order ​

Use order when a column needs to sort by meaning instead of alphabetically — a status column that should read Draft → Active → Pending → Termed, or a coverage tier that should read Employee → Employee + Spouse → Family. Ranks sort lowest first, 0 and negative numbers work as you'd expect, and numeric strings are coerced. sortType: 'order' is optional — defining order is enough — but it documents the intent.

The rank can be declared three ways:

order valueMeaning
stringThe name of another property on each row holding that row's rank, e.g. order: 'statusOrder' with rows like { status: 'Pending', statusOrder: 1 }. Use this when the rank comes down from the server alongside the value.
objectA map of cell value to rank, e.g. order: { high: 1, medium: 2, low: 3 }.
arrayThe values in the order you want them, where the array index is the rank, e.g. order: ['Draft', 'Active', 'Pending', 'Termed'].

Values that can't be ranked — missing from the map or array, or a row rank that is missing, empty, or not a number — sort last, and tie-break alphabetically among themselves. Rows sharing the same rank keep their original relative order.

Each of the last three columns below declares its rank a different way. Unmapped, unranked, and Waived have no rank, so they sort last in every case.

Custom compare function ​

For a comparison that doesn't fit any sortType, pass compare. Here the plan column sorts by the length of the plan name.

Column alignment ​

Column alignment works the same as on EnTableBasic: set class on the heading object to apply a CSS class to both the sortable header and every cell in the column — e.g. class: "text-right" to right-align a currency or numeric column. The demo at the top of this page right-aligns its Date of Birth column exactly this way. See the table guidelines for when to right-align.

Types ​

SortableTableHeading - Object
NameTypeDescription
labelstring

Display text for the column header.

srLabelstring

Screen-reader-only name for the column, rendered in addition to label. Use it to name a spacer column that has no visible heading (a lock toggle, row actions, an icon), so the column is not announced as blank.

keystring

Identifier for the location of the data for this column.

slotstring

The name of the slot created for the data in the cell and the header; defaults to the key unless a value is provided.

classstring

Applies a CSS class to both the header and the table cell.

headerClassstring

Applies a CSS class to just the header.

widthnumberstring

Sets the column's width, rendered as a <col> so it applies to the header and every cell without repeating. A number is treated as pixels; a string is used verbatim, so '20%', '12rem' and 'auto' all work. Honoured under the default automatic layout, with two exceptions: a column whose content cannot wrap narrower than the width given (a long unbroken code) grows to fit it, and widths that together exceed the table are scaled down to fit. fixedLayout removes both exceptions.

renderInTableboolean

Filters the heading out of the table so it will not display.

activeboolean

Whether this column's sorting should be active or not.

reversedboolean

Whether this column's sorting should be reversed or not.

isSortableboolean

Whether this column is sortable.

sortType"none""numeric""date""order"

Specify how to sort the data when sorting is used.

orderCustomOrder

Custom (non-alphabetical) ordering for the column's values. Sorted numerically by rank, lowest first (negatives and 0 supported); values without a rank sort last and tie-break alphabetically. Takes precedence over string sorting and over compare, but is ignored when sortType is 'numeric', 'date' or 'bulk-select'.

compareCompareFn

Custom compare function for sorting.

CompareFn - function
NameTypeDescription
a*—
b*—