Skip to content

EnTableBasic ​

Preview ​

Props ​

NameDescriptionDefaultControl
headings

An array containing the labels for the columns of the table and optional key that matches to data in the row object.

array
[…]complex 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
draggableRows

Lets rows be re-ordered by dragging, and moved between groups when the table is grouped. Adds a drag handle column that is also operable by keyboard.

The table never reorders its own data — each completed move is emitted as row-move for the consumer to apply. Both ends of that payload index the data handed in (rows, or the group's own rows when grouped), so a paginated table reports positions the consumer can splice with rather than positions within the page on screen.

A row opts out with draggable: false, leaving it stationary while still accepting drops. The flag needs somewhere to live, so it applies to object rows only; with rowType: 'array' every row is draggable.

boolean
false
dragChannel

Shared name that lets separate tables exchange rows, the way sortablejs uses group. Tables on the same channel accept each other's rows and the arrow keys step between them. Left unset, a table only accepts its own rows.

string
""
dragId

Identifies this table within its channel. Echoed on both ends of row-move, so a consumer owning several tables knows which list to move the row out of and into. Defaults to a generated id, which is enough when only drag order matters.

string
""
dragLabel

This table's name, used when announcing a move into it.

string
""
dropZone

An element outside the table that stands in for the whole of it as a drop target — the panel a bucket sits in, so a row can be dropped anywhere on the panel rather than only on the rows. As a string it is a selector for the closest ancestor of the table; an element is used as given. A drop there lands at the end of the last group. The element is not styled; the table lights up while a drag is heading for it, wherever the pointer is.

string | Record<string, any>
null
rowKey

Names a row's stable identity, as a property name or a function of the row. Only consulted when draggableRows is on: keyed by position, Vue would repaint the row in each slot and leave a focused drag handle pointing at whichever row had taken its place.

Rows moved between arrays by reference are tracked by object identity and need not set this. Name a key when the rows are rebuilt on every update.

string | Function
""
emptyDropText

Placeholder shown when a draggable table or group has no rows left. An empty <tbody> collapses to zero height, leaving a pointer nothing to drop onto.

string
"Drop a row here"

Slots ​

header

render table rows

default

No description

${heading.slot}-heading

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

Variables
NameTypeDescription
headingobject

the defined heading object

group-heading

No description

Variables
NameTypeDescription
groupunknown—
group-indexunknown—

drop-zone

Placeholder row shown when a `draggableRows` table or group has no rows left, so the emptied destination can still be dropped onto; defaults to the `emptyDropText` prop

Variables
NameTypeDescription
group-indexnumber

Index of the emptied group, or 0 when the table is not grouped

${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

group-total

Label cell of the totals row closing each group; rendered when the group has a `totals` object and some heading sets `total: true`

Variables
NameTypeDescription
groupobject

The group being totalled

group-indexnumber

Index of the group

totalsobject

That group's totals, keyed by column key

body

render table rows

Variables
NameTypeDescription
rowsArray.<object>

The rows currently rendered, after pagination

headingsArray.<object>

Resolved column definitions in render order, matching the header

cell-contentsfunction

(value, headingIndex) formatter used by the default cells

footer

Label cell of the whole-table totals row in the `<tfoot>`; rendered when the `totals` prop is set and some heading sets `total: true`

Variables
NameTypeDescription
totalsobject

The grand totals, keyed by column key

Events ​

row-move

No description

update:model-value

No description

Methods ​

No methods defined.

Types ​

BaseTableHeading - 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.

Examples ​

Using dynamically created column slots ​

A slot is created for each column for better control of the display values. The name of the slot is generated from the key in the headings object or a defined slot key. The component will automatically convert PascalCase to kebab-case when creating the slot names. Inspect the Vue devtools to see the exact name of the resolved slot name in the mappedHeadings computed property.

Using bulk actions ​

enable-bulk-action adds a checkbox to every row and a select-all checkbox to the heading row. The select-all is a parent checkbox: checking it selects every row, clearing it clears them, and when only some rows are selected it shows the indeterminate (partly checked) mark rather than reading as unchecked. Grouped tables get the same per group through group-select-all. This is Beacon's precedent for any parent checkbox over a set of children — see EnInputBoolean for the standalone case.

Grouped rows ​

Pass groups (an array of { label, rows }) instead of rows to render one <tbody> per group, each opening with a colspanned heading row. Grouped mode bypasses pagination — all groups render. Combine with enable-bulk-action and group-select-all to add a per-group select-all checkbox to the group headings; the shared v-model still holds the flat selection.

Totals rows ​

A table can close with a grand total, and a grouped table can close each group with its own. Two things opt a column in:

  • Mark the columns that total. Set total: true on the heading. A totals row renders a cell for every column, but only the marked ones show a value, so a totals object deserialized from the same model as a row (every property present, the non-aggregated ones null) renders correctly.
  • Hand in the totals. The totals prop renders a <tfoot> beneath every row; a group's own totals object renders as the last row of that group. Both are keyed by column key and pass through the same formatter as the cells above them.

The label cell spans every column up to the first totalled one, so the numbers sit under the columns they sum. The footer slot replaces its default "Total"; the group-total slot replaces a group's default <label> Total, or set totalLabel on the group instead.

The example also turns off showGroupHeadings: each group already names itself in its subtotal row, so a heading band above it would be redundant. Keep the headings when the rows do not identify their group on their own. A group-select-all checkbox lives in the heading row, so that option forces it to render regardless.

Totals rows are exported too. The toolbar's CSV download pads a colspanned label cell with one empty field per column it spans, so the numbers in the CSV stay under their headers.

Blank cells ​

A null, undefined or empty-string value renders as nothing. Give the heading a blankValue and that placeholder renders instead, ahead of any formatter (which, handed null, would usually emit junk like $NaN). Zero and false are real values and never blank.

The placeholder is for the reader, not the file: a CSV export writes an empty field where the table shows the placeholder.

Column widths ​

Give a heading a width and the column is sized for you. It renders as a <col>, so one declaration sizes the header and every cell in that column — no utility class repeated per heading, and a column with no visible label can still be sized.

A bare number is treated as pixels; a string is used verbatim, so '20%', '12rem' and 'auto' all work.

With the default automatic table layout a width is a strong hint — long content in a cell can still push past it. Add the fixedLayout prop to make it binding: it applies en-style's table-fixed, and the widths become the widths. EnTableSortable forwards the prop too.

Naming a column that has no visible heading ​

A spacer column — a row-actions cell, a lock toggle, an icon — is announced as blank unless it is named. srLabel renders a screen-reader-only name in addition to label, so a column can be visually empty and still announced.

Re-orderable rows ​

draggable-rows lets the reader put rows in their own order by dragging, and move them between groups when the table is grouped. It adds a trailing drag-handle column, so the handle and a bulk-action checkbox sit at opposite ends of the row. The handle is a real button: tab to it and use Up/Down to move a row within its group, Left/Right to move it to the previous or next group. Each keyboard move is announced to screen readers.

The table never reorders its own data. Every completed move is emitted as row-move with { row, from, to }, and you apply it: lift the row out at from.rowIndex, then insert it at to.rowIndex, which is already the position once the row has been lifted out. Both indices point into the data you passed in (rows, or the group's rows), not the page on screen, so the same handler works on a paginated table.

A row with draggable: false stays where it is and gets no handle, but rows can still be dropped around it. When a group is emptied it shows a placeholder row so it can still be dropped onto; set the text with empty-drop-text, or replace it with the drop-zone slot.

Move every row out of a group to see the placeholder.

Separate tables can exchange rows too. Give each the same drag-channel and its own drag-id; both ends of row-move carry a tableId, so one handler can tell which array to splice out of and into. Listen for row-move on every table on the channel: a drop is reported by the table that receives the row, but a keyboard move by the table it left. Name the channel for the feature it belongs to (oe-plan-buckets, not plans), because channels are matched page-wide. drag-label names a table in the move announcement, and drop-zone lets an ancestor element, such as the panel a table sits in, accept a drop anywhere on it.

Rows that are rebuilt on every update lose their identity between renders, which would leave keyboard focus on whichever row took the moved row's place. Name a stable key with row-key in that case.

Re-ordering is not available on EnTableSortable: sorting decides the row order there, so there is no order of yours for a drag to change.

Expandable rows (master-detail) ​

For a summary row that expands to reveal the detail behind it — an audit trail, a nested breakdown, extended record fields — use EnTableRowDetail. It renders the data row and its collapsible detail row as sibling <tr>s, so it composes with this component through the body slot (which hands you the entire <tbody> for custom row rendering, and passes the paged rows, the resolved headings and the cellContents formatter so hand-rendered cells can match the default ones).

Matrix table (columns per entity) ​

Columns don't have to be fixed data fields. Because headings is an array you supply and each column gets its own slot, a column can represent a repeated entity — one column per household member, per location, per month — with each cell showing that entity's status for the row. Rows stay the records (here, elected plans); the matrix falls out of the headings you build.

The example below is a coverage matrix: one row per elected plan, one column per household member, and each cell marked covered or not covered.

Three documented pieces do the work:

  • Columns — compute headings from the entities. One entry per member, each with its own key.
  • Cells — a per-column slot (#<slot>="{ row }") renders the status mark. You need a slot rather than a plain value because cell values are interpolated as text and can't carry an icon.
  • Two-line headers — the #<slot>-heading slot takes arbitrary markup, so a first name can sit above a relationship.

Mark status with a glyph and an em dash rather than color, so it survives black-and-white printing — the print stylesheet strips color entirely.

Give every status cell an accessible name

A glyph rendered through an icon-* class announces nothing to a screen reader, and an em dash announces nothing useful — so a matrix built from glyphs alone loses exactly the meaning it exists to convey. Pair each cell with sr-text: <span class="sr-text">Covered</span>. This is required whichever glyph you use.

The demo names its slots statically because the household is fixed. For a variable number of entities, generate both the headings and the slots from the same list, using dynamic slot names:

vue
<EnTableBasic :rows="rows" :headings="headings">
  <template v-for="m in members" #[m.key + `-heading`]>
    <div>{{ m.firstName }}</div>
    <div class="text-smaller text-muted">{{ m.relationship }}</div>
  </template>
  <template v-for="m in members" #[m.key]="{ row }">
    <span v-if="row[m.key]" class="icon-check-circle-solid">
      <span class="sr-text">Covered</span>
    </span>
    <span v-else><span class="sr-text">Not covered</span>&mdash;</span>
  </template>
</EnTableBasic>

Keep an eye on width as the entity count grows — pair a wide matrix with table-responsive so it scrolls rather than overflowing, and see the table utilities for table-sticky if the header needs to stay visible.

Spanning a row across columns ​

Sometimes a single row needs to replace several of its cells with one piece of content that runs across them — an IRS disclaimer sitting where a spending-account row's per-member cells would go, a "no data for this period" note, a sub-total caption. Render the rows yourself through the body slot (the component supplies the <tbody>, you supply the <tr>s) and give the wide cell a plain colspan. No special component is involved.

Pair it with table-fixed — it pins the column widths so the long spanning cell can't stretch its columns and reflow every other row. Column widths are then taken from the header row.

This is a different pattern from EnTableRowDetail, which adds a separate, collapsible row spanning every column beneath a summary row. Use that for master-detail; use this when one always-visible row spans some of its columns.

Column alignment for numeric and currency columns ​

Column alignment is declared per column on the heading object. The class property applies a CSS class to both the column header and every cell in the column, so the two always stay aligned with each other — use it with the text-right utility to right-align currency and other numeric columns so the decimal points line up, or with text-center to center-align a column whose content is a fixed width, such as an icon action column (Edit, Delete), especially at the end of the table. The same mechanism takes any utility class — e.g. text-nowrap to prevent a column (or, via headerClass, just its header) from wrapping, or text-wrap to force long unbroken content to wrap within the column. (Use headerClass instead of class whenever only the header should be affected, as in the fixed-width example above.) The same heading properties work on EnTableSortable.

See the table guidelines for when to align which way: currencies and other numbers read best from the right, fixed-width content like icons can be centered, and headers should match the alignment of their column's content.