List

WList renders a paginated collection as a table on desktop and as cards on mobile. It owns pagination, selection, column settings (show, hide, reorder, resize) and ordering. You give it:

• useQueryFn and queryParams — a paginated query.
• fields — one component per column. Each has a meta export with its title, width, ordering field and CSS class, and renders one cell from item.
• cardColumns and cardAreas — the card layout as a CSS grid, with field labels as area names. Every field must appear in cardAreas, even ones hidden by default; a field left out renders in an extra grid column.
• Optionally an expansion component for a detail row and a menu component for row actions.

The List with fields recipe builds this step by step; the list below is its result.

Growth

Caretaker

Layout variables

The sticky header, the checkbox column and full-width rows position themselves from the app's layout variables — --header-height, --nav-bar-width, --actions-bar-width and --inner-margin — so the app has to set them (see App shell). Inside a modal, the modal sets its own.

Bulk actions

Above the table is the selection bar, WButtonSelection. While nothing is selected it shows the action components and the list settings; while items are selected, the bulk components and a "Selected N items" counter with a clear button. Actions that don't fit move into a More menu.

Each action is a component that renders a WButtonSelectionAction — an icon with a title, hidden on phones. A bulk action gets BulkProps: selectionCount, queryParamsGetter() for the query params narrowed to the selection, readonly, disableMessage, which disables the button with that text as its tooltip while nothing is selected, and clearSelection() to reset the selection when it is done.

Call clearSelection rather than emitting clear:selected, which still works but is deprecated. An action that doesn't fit the bar renders in the More menu, and a confirm opened from there takes the menu's place, unmounting the action — an emit after the confirm is accepted never arrives.

<template>
  <WButtonSelectionAction
    title="Archive"
    :icon="markRaw(IconArchiveBook)"
    :disable-message="disableMessage"
    :disabled="readonly"
    @click="archive"
  />
</template>

<script lang="ts" setup>
import {markRaw} from 'vue'

import type {BulkProps} from 'eco-vue-js/dist/components/List/types'

import WButtonSelectionAction from 'eco-vue-js/dist/components/Button/WButtonSelectionAction.vue'

import IconArchiveBook from 'eco-vue-js/dist/assets/icons/IconArchiveBook'

const props = defineProps<BulkProps<QueryParamsPlants>>()

const archive = () => plantApi.archive(props.queryParamsGetter()).then(() => props.clearSelection())
</script>

WButtonUnselect is the small round clear button of the select chips.

Filters

WListFilter renders filter components for query params held in a Uniform form's scope — usually a form over the route query. Each filter is a component with a meta export (its title, icon and the fields it sets) that gets scope, global and readonly. search adds a text search for the search param, or filterSearch for your own.

In place, the filters are chips in a row: the set ones are shown, and a button adds another. With global they go into the app shell instead — the filters into the actions bar's panel and the search into the header bar — with a button that resets them. disabledFilterFields leaves out filters for params the page fixes. pinned filters are always shown, first, and their remove button only clears them. The List with fields recipe builds a set of filters for its list.

WListHeader and WListHeaderItem are the table header row of the list, with the select-all checkbox and sortable, resizable column titles. WList renders them from fields.

Filters in the selection bar

Put the WListFilter in WList's filter slot to show it at the start of the selection bar, on one line with the list actions and the list settings. Chips that do not fit go into a "more" chip that opens them as a list, and the list actions, which move to the end of the bar, fold into More before any chip does. While rows are selected, the selection with its bulk actions replaces the filters, so the bar keeps its height. On phones the filters take a row of their own above the actions, and the search narrows for them. --w-list-toolbar-height (w-list-toolbar-h-*) sets the height of the bar's inputs, chips and actions, by default the inherited input height.

Each chip names its filter and, when set, the picked values. A filter's meta.summary returns them from the query params, such as the titles of the picked options; without it the chip shows how many values are picked. A chip in the "more" list can be removed there too.

Groups

groupBy tells whether two neighbouring items belong to the same group, and the group slot renders a heading before the first item of each group and before the first item rendered. Only neighbours are compared, so the query has to sort by the field the list groups by.

The items of all loaded pages share one layout. A group runs on across pages without a new heading, and in the grid a page that ends in the middle of a row is continued in that row by the next one. The list places the heading: it takes a row of its own in the grid, stays under the toolbar while its group scrolls past and, in list mode, stays at the left edge when the rows scroll sideways. The slot gives its content and lays it out.

Nested fields

A field's meta can hold fields instead of being a column itself. Its columns then show a related object or every item of an array:

• keyEntity, or getterEntity for a computed one, gives the nested field components that object as item.
• keyArray, or getterArray, repeats the columns once per array item, one line each. The items need an id. componentItem wraps each line, for example to draw a separator between them.
• With neither, fields only groups the columns, such as to place them in one card area.

In the table, nested columns are list columns like any other: each has its own header and width, can be hidden in the list settings, and lines up across the rows, including each line of an array. In a card, a nested field is a flex row. cssClass styles it, cssClassArray styles the wrapper of an array's lines, and [grid-area:…] places it in one of cardAreas; pick labels without _ for that, since Tailwind reads _ in a class as a space.

In the table, the root of componentItem is a line of the table, and each of its children spans the whole line. Put a separator next to <slot />, not around it.

Rows with lines of an array are taller than one line, so the demo uses align-top. The checkbox and the row menu then sit --w-list-align-top from the top of the row. Set it with w-list-align-top-* on WList to match the row's top padding and first line: here the rows have py-2, and w-list-align-top-2.5 centers the box on the first line.

Name

Kind

Caretaker

Role

Task

Due

API

WList

import WList from 'eco-vue-js/dist/components/List/WList.vue'

Props

Prop	Type	Default	Description
count	number	—	Total number of items, when known in advance. Sizes the skeleton and the select-all. Defaults to the count the query returns.
fields	Fields	required	Field components, one per column, each with a meta export for its title, label, ordering field and classes. A meta with fields groups nested fields.
expansion	ExpansionComponent<Data, QueryParams>	—	Detail component shown under a row when the row is clicked. Receives the same props as a field, except config.
useQueryFn	UseQueryDefault<PaginatedResponse<Data>, QueryParams>	required	Paginated query the pages are loaded with.
useQueryFnExport	UseQueryDefault<PaginatedResponse<Data>, QueryParams>	—	Paginated query for export, when it differs from useQueryFn.
queryParams	QueryParams	required	Params for useQueryFn. An ordering param drives the sort controls and the sortable column headers.
queryOptions	DefaultQueryOptions<PaginatedResponse<Data>>	—	Options for every page query.
bulkDisableMessage	string	—	Tooltip on the bulk actions while nothing is selected. Defaults to "No selected items".
selectionTitle	string	required	Singular noun in the "Selected N items" counter of the selection bar.
bulk	BulkComponent<QueryParams>[]	—	Actions in the selection bar while items are selected. Each gets the selection count and a getter of the query params narrowed to the selection. The ones that do not fit the bar move into a More menu.
action	ActionComponent<QueryParams>[]	—	Actions in the selection bar while nothing is selected, with the current query params.
menu	MenuComponent<Data>[]	—	Row menu items, opened by the row's more button or a right click. A [component, props] tuple passes extra props.
readonlyGetter	((item: Data) => boolean)	—	Makes a single row readonly.
cardClass	string	—	Classes for each row's content box.
cardWrapperClass	string	—	Classes for each row's outer box.
selectAllTextGetter	(isUnselect: boolean, count: number) => string	required	Tooltip of the select-all checkbox in the table header.
hasBorder	boolean	—	Draws a border around each row.
configKey	string	required	localStorage key the column settings and view mode are saved under.
defaultConfigMap	FieldConfigMap<Fields>	required	Width, visibility, order and stickiness of each field by label, until the user changes them.
defaultMode	ListMode	ListMode.TABLE	Table or grid view, until the user picks one. Small screens always show cards.
alignTop	boolean	—	Aligns cells, the checkbox and the row menu to the top of the row instead of centering them. --w-list-align-top (w-list-align-top-*) sets how far the checkbox and the menu are from the top, 1.125rem by default, so they line up with the first line of the cells.
disableMore	boolean	—	Disables the row menu, both the more button and the right click.
readonly	boolean	—	Makes every row readonly, and passes readonly to the bulk, action and menu components. When unset, inherits the readonly state provided by a parent.
noOrdering	boolean	—	Hides the sort control and makes the column headers not sortable.
formFieldGetter	((data: Data, index: number) => string | undefined)	—	Wraps a row in WUniform for the returned field of uniformScope, so its fields can edit the item as part of a form. undefined leaves the row unwrapped.
uniformScope	UniformScope<Data[]>	—	Form scope of the items, for formFieldGetter.
groupBy	((a: Data, b: Data) => boolean)	—	Whether two neighbouring items are in the same group. The group slot renders before each new group.
cardColumns	CardColumns	required	Column widths of the card grid.
cardAreas	CardAreas<Fields, CardColumns["length"]>	required	Rows of the card grid, as area names: field labels, AREA_SELECT, AREA_MORE or .. Areas of hidden fields are dropped, and so are rows and columns left empty.
cardTo	((item: Data) => RouteLocationRaw | undefined)	—	Route a row links to.
hasAction	boolean	—	Makes a row click emit click:action.
noHeaderSettings	boolean	—	Hides the column settings button, and neither loads nor saves column settings.
noRefetch	boolean	—	Hides the refetch button.
refetchInterval	number	—	Refetches the loaded pages every this many ms.
apiMethodExport	((queryParams: QueryParams) => Promise<Data[]>)	—	Loads the items to export in one call, instead of paging through the export query.
exportFileName	string	—	Name of the exported file.
disableExport	boolean	—	Hides the export button. Rows are then selectable only with bulk or alwaysSelect.
alwaysSelect	boolean	—	Shows the checkboxes even without bulk or export, and makes a row click toggle its selection. With cardTo, the row link moves into a View menu item.
selection	Selection<number>	—	Selected items, controlled from outside with update:selection. By default the selection is kept in the URL hash.
noHeaderUpdate	boolean	—	Keeps the sticky list header out of the app header bar's padding while scrolled.
minHeight	boolean	—	Drops the full-screen minimum height and the bottom padding, for a list inside other content.
toMarkdown	((data: Data, index: number) => string)	—	Converts an item to Markdown. Adds a Copy as Markdown item to the row menu and a Markdown option to export.
noMode	boolean	—	Hides the table and grid switch in the column settings.
disableSelect	boolean	—	Hides the checkboxes and turns selection off.
selectOnly	boolean	—	Allows only picking rows one by one — no select-all and no Shift range selection.
contentVisibility	boolean	—	Skips rendering rows outside the viewport with content-visibility: auto, for long lists.

Events

Event	Payload	Description
update:error	(ApiError<{}, ErrorResponse<{}>>)	A page query failed.
click:action	(CardActionParams<Data>)	A row was clicked, with hasAction. Carries the item, a setter that replaces it and its form scope.
update:query-params	(QueryParams)	The changed params only — the new ordering, from the sort control or a column header.
update:count	(number | undefined)	Total count returned by the query.
update:selection	(Selection<number>)	The new selection, with selection.

Slots

Slot	Props	Description
header	{ count: number | undefined; }	Content above the selection bar, with the count returned by the query.
filter	—	Filters at the start of the selection bar, usually a WListFilter. They keep to one line, the chips that do not fit go to a menu, the list actions move to the end and fold into More first, and a selection replaces them. --w-list-toolbar-height sets the bar's height, the inherited input height by default.
selection	—	Replaces the buttons at the end of the selection bar — range select, refetch, sort and column settings.
group	{ item: Data; previous: Data | undefined; skeleton: boolean; }	Content of the heading before each group of rows, with groupBy. The heading spans the whole row, sticks under the toolbar and, in list mode, to the left edge while the rows scroll sideways. Its content is laid out by the slot. skeleton is true while the page loads.
empty	—	Shown instead of the rows when the query returns no items.
error	{ error: Error; retry: () => Promise<void>; isFetching: boolean; }	Shown instead of a page that failed to load and has nothing cached. Gets the error, retry to load the page again, and isFetching. Replaces the message and Retry button.

WListCardField

import WListCardField from 'eco-vue-js/dist/components/List/WListCardField.vue'

Props

Prop	Type	Default	Description
modelValue	string | number	—	Value shown as truncated text. The inner and default slots replace it.
skeleton	boolean	—	Shows a placeholder instead of the content.
allowOpen	boolean	—	Lets clicks through to the row, so they open its expansion.

Slots

Slot	Props	Description
default	—	Replaces the whole content, including the truncating wrapper.
inner	—	Replaces modelValue inside the truncating wrapper.

WButtonSelection

import WButtonSelection from 'eco-vue-js/dist/components/Button/WButtonSelection.vue'

Props

Prop	Type	Default	Description
title	string	"item"	Singular noun in the "Selected N items" counter. An "s" is added for more than one.
disableMessage	string	"No selected items"	Tooltip of the actions while nothing is selected, which also disables them.
selectedCount	number	—	Number of selected items. While it is above 0, the counter with a clear button replaces the settings slot.

Events

Event	Payload	Description
clear:selection	—	The clear button of the counter was clicked.

Slots

Slot	Props	Description
default	{ disableMessage: string | undefined; cssClass: string; visibleCount: number; }	WButtonSelectionAction buttons. Pass them disableMessage, and cssClass for the dividers between them. Hide the ones from visibleCount on, which do not fit — the more slot shows them instead.
more	{ disableMessage: string | undefined; cssClass: string; visibleCount: number; }	Actions in the More menu at the end of the row: the ones of the default slot from visibleCount on, which do not fit the row. The menu shows only when some do not.
filter	—	Filters at the start of the bar while nothing is selected. The actions then move to the end, beside settings, and the selection replaces the filters.
settings	{ isFilterShown: boolean; }	Content at the end of the bar while nothing is selected, such as list settings.

WButtonSelectionAction

import WButtonSelectionAction from 'eco-vue-js/dist/components/Button/WButtonSelectionAction.vue'

Props

Prop	Type	Default	Description
title	string	—	Text after the icon. Hidden on phones, except in the More menu.
label	string	—	Name for screen readers. Defaults to tooltipText, then title.
icon	SVGComponent	required	Icon of the action.
disableMessage	string	—	Disables the action and shows this text in its tooltip, e.g. "No selected items".
disabled	boolean	—	Disables the action.
active	boolean	—	Marks the action as on, e.g. a filter that is applied.
loading	boolean	—	Shows a spinner over the action and ignores clicks.
tooltipText	string	—	Tooltip text.
to	RouteLocationRaw	—	Router location — renders a router link. Needs vue-router installed in the app.
tag	keyof HTMLElementTagNameMap	—	Element rendered without to, e.g. a for a link with href. Defaults to button.
href	string	—	Link URL when tag is a.
target	"_self" | "_blank" | "_parent" | "_top"	—	target attribute of the link.
replace	boolean	—	Replaces the current history entry instead of adding one, with to.

Events

Event	Payload	Description
click	(value: MouseEvent)	The action was clicked, unless it is disabled or loading.

Slots

Slot	Props	Description
default	—	Slot for absolute positioned content, like counter
tooltip	—	Rich content of the tooltip, replacing disableMessage or tooltipText.

WButtonSelectionState

import WButtonSelectionState from 'eco-vue-js/dist/components/Button/WButtonSelectionState.vue'

Props

No props.

Events

Event	Payload	Description
click	(value: MouseEvent)	The clear button was clicked.

Slots

Slot	Props	Description
default	—	The selection count, such as "Selected 3 items".

WButtonUnselect

import WButtonUnselect from 'eco-vue-js/dist/components/Button/WButtonUnselect.vue'

Props

Prop	Type	Default	Description
disabled	boolean	—	Disables the button.
loading	boolean	—	Ignores clicks, e.g. while the value is saving.

Events

Event	Payload	Description
click	(value: MouseEvent)	The button was clicked, unless it is disabled or loading.
mousedown	(value: MouseEvent)	A mouse button was pressed on it, unless it is disabled or loading.

WListFilter

import WListFilter from 'eco-vue-js/dist/components/List/WListFilter.vue'

Props

Prop	Type	Default	Description
scope	UniformScope<QueryParams>	required	Scope of the Uniform form that holds the query params, usually synced with the route query.
filter	FilterComponent<QueryParams>[]	—	Filter components, one per filter, each with a meta export. A tuple adds props for it.
pinned	FilterComponent<QueryParams>[]	—	Filters of filter always shown as chips, first, instead of behind "Add filter". Their remove button only clears them.
filterSearch	FilterComponent<QueryParams>	—	Component for the search field, instead of the default text search on search.
disabledFilterFields	(keyof QueryParams)[]	—	Query params that can't be changed, e.g. fixed by the page. Their filters are left out.
search	boolean	—	Adds a search field for the search query param.
global	boolean	—	Puts the filters in the actions bar's filter panel and the search in the header bar, instead of in a row in place.
readonly	boolean	—	Shows the filters without changing them.
searchVisible	boolean	—	Deprecated: No effect: the search field is always shown in place, and behind the header's search button with global.

WListHeader

import WListHeader from 'eco-vue-js/dist/components/List/WListHeader.vue'

Props

Prop	Type	Default	Description
columns	string	required	Track sizes of the columns between the checkbox and the end cap, as in grid-template-columns. The rows use the same tracks, so the cells line up with them.
allowSelect	boolean	—	Shows the select-all checkbox.
selectOnly	boolean	—	Keeps the checkbox column's space without the checkbox, for lists without select-all.
hideMore	boolean	—	Narrows the end cap when the rows have no menu.
disabled	boolean	—	Disables the checkbox.
count	number	—	Total number of items. The checkbox is disabled while it is 0 or unknown.
selection	boolean | null	—	State of the select-all checkbox: true for all, null for some, false for none.
tooltipText	string	required	Tooltip of the select-all checkbox.

Events

Event	Payload	Description
update:header	—	The header was mounted or unmounted, for the sticky header to measure it.
toggle:selection	(value: boolean)	The select-all checkbox was toggled.

Slots

Slot	Props	Description
default	—	WListHeaderItem cells, one per column.
settings	—	Content of the end cap, such as the column settings button.

WListHeaderItem

import WListHeaderItem from 'eco-vue-js/dist/components/List/WListHeaderItem.vue'

Props

Prop	Type	Default	Description
title	string	—	Title of the column. The default slot replaces it.
field	Field	required	Ordering field of the column. Without it, the title isn't a sort button.
ordering	OrderItem<Field>[]	required	Current ordering, to show the column's direction and position in it.
disabled	boolean	—	Turns sorting off.
allowResize	boolean	—	Adds a handle to resize the column.
itemClass	string	—	Class of the title, replacing the default bold one-line style.
styleValue	Record<string, string | undefined> | undefined	required	Style of the column, such as its sticky offsets.

Events

Event	Payload	Description
update:width	(number)	The column is being resized to this width.
save:width	—	Resizing ended, to save the width.
update:ordering	(OrderItem<Field>[])	The title was clicked: descending, then ascending, then off. Other columns stay in the ordering after it.

Slots

Slot	Props	Description
default	—	Title of the column, replacing title.