---
url: "https://vueda.dev/v3/reference/api/vue/ViewList.md"
title: "ViewList"
---

# ViewList

## Overview

Full-page list view for a Django model. Renders a paginated, sortable, and searchable data grid with support
for column hiding, filter groups, bulk actions, targetless actions, workflow transitions, column totals, and
switching between paginated and show-all display. Persists sort order, visible columns, and active filters
across page visits via the list preference store.

Theme entry: [ViewList](/v3/reference/theming/keys/ViewList.md)

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| <span id="prop-iconOverride">iconOverride</span> | `Object` |  | `null` | A partial icon registry (`{ [componentName]: { [iconName]: { component, props } } }`) merged with inherited and default icon entries; scopes icon overrides to this component and its descendants. |
| <span id="prop-themeOverride">themeOverride</span> | `Object` |  | `null` | A partial ThemeObject keyed by component name, merged over this component's theme and provided to descendants. |
| <span id="prop-app">app</span> | `string` | yes |  | Django app label that owns the model. |
| <span id="prop-model">model</span> | `string` | yes |  | Django model name used to resolve API endpoints and configuration. |
| <span id="prop-listFields">listFields</span> | `array` |  | `[]` | Field names to fetch; uses the `displayFields` keys, then the model config default, when empty. |
| <span id="prop-displayFields">displayFields</span> | `object` |  | `{}` | Map of field names to display configuration overrides (label, component, etc.). |
| <span id="prop-columnComponents">columnComponents</span> | `object` |  | `{}` | Per-field list column adapter overrides. Each value is a component, a `() => component` function, or a string key into `availableColumns`. Takes precedence over `modelConfig.config.columnComponents` and type defaults; a consumer `#field(<col>)` slot still wins over both. |
| <span id="prop-columnProps">columnProps</span> | `object` |  | `{}` | Per-field props forwarded to the resolved list column adapter. |
| <span id="prop-relatedObjectsRules">relatedObjectsRules</span> | `object` |  | `{}` | Rules mapping related object keys to fetch data alongside each list row. |
| <span id="prop-calculatedObjectsRules">calculatedObjectsRules</span> | `object` |  | `{}` | Rules mapping calculated object keys to derive computed data alongside each list row. |
| <span id="prop-params">params</span> | `object` |  | `{}` | Additional query parameters merged into every API request. |
| <span id="prop-scopes">scopes</span> | `object` |  | `{}` | Declares which `params` keys are shown as scopes in the constraints band, keyed by `params` key: `{ [key]: { label?, clearable? } }`. A declared key is shown while `params` carries a value for it. `label` defaults to the filter's metadata label (or the key) with its value; `clearable` defaults to true. Clearing emits `clear-scope`; the caller removes those keys from `params`. Undeclared `params` keys stay plain request parameters. |
| <span id="prop-tableBreakpoint">tableBreakpoint</span> | `string` |  | `"lg"` | Tailwind breakpoint at which the layout switches from card to table view. |
| <span id="prop-extraFieldObjects">extraFieldObjects</span> | `array` |  | `` [     {         name: `selected_`,         extra: true,         label: "Selected",     }, ] `` | Extra synthetic field objects appended to the field list (e.g. the `selected_` checkbox column). |
| <span id="prop-filterables">filterables</span> | `array` |  | `undefined` | List of field names to show as filters; overrides the server-provided list when set. |
| <span id="prop-filterableDetails">filterableDetails</span> | `object` |  | `{}` | Per-field filter detail overrides merged with server-provided configuration. |
| <span id="prop-pageSizeOptions">pageSizeOptions</span> | `array` |  | `[...DEFAULT_PAGE_SIZE_OPTIONS]` | Rows-per-page options offered by the pagination footer; the final `"all"` entry loads every page at once. |
| <span id="prop-defaultPageSize">defaultPageSize</span> | `number\|string` |  | `DEFAULT_PAGE_SIZE` | Initial rows-per-page when no preference is stored (a number, or `"all"`). A stored preference overrides it. |
| <span id="prop-showTotalRecordNum">showTotalRecordNum</span> | `boolean` |  | `undefined` | When true, displays the total record count in the pagination bar. Overrides the model config's `showTotalRecordNum`; when unset, the model config decides, defaulting to true. |
| <span id="prop-allowColumnHiding">allowColumnHiding</span> | `boolean` |  | `undefined` | When true, shows a column-visibility selector so users can hide individual columns. Overrides the model config's `allowColumnHiding`; when unset, the model config decides, defaulting to false. |
| <span id="prop-primaryActions">primaryActions</span> | `array` |  | `undefined` | Action names promoted to the filled hero CTA in the page title; defaults to the `create` action. |

## Slots

| Name | Scoped | Description |
| --- | --- | --- |
| `targetless-action-buttons` | yes |  |
| `targetless-action-button` | yes | Replaces an individual targetless action button. |
| `search` | yes |  |
| `columns-select` | yes |  |
| `columns-select-value-label` |  |  |
| `additional-errors` |  |  |
| `before-list` |  |  |
| `` `field(${name})` `` | yes |  |
| `row-after-objects` | yes |  |
| `bulk-action-button` | yes | Replaces an individual bulk action button. |
| `workflow-action-button` | yes | Replaces an individual workflow/transition action button. |

[Full slot reference](/v3/reference/api/vue/ViewList/slots.md)

## Events

| Name | Description |
| --- | --- |
| `selected` | Emitted once on mount with a live ref to the selected primary keys (`actions.selectedObjects`). |
| `sorted` | Emitted once on mount with a live ref to the active sort order (`sort.sorting.state.sorted`). |
| `objects` | Emitted once on mount with a live ref to the raw fetched objects (`list.instanceList.state.objects`). |
| `order` | Emitted once on mount with a live ref to the current object ordering (`list.instanceList.state.order`). |
| `loading` | Emitted once on mount with a live ref to the combined loading state (`list.loading`). |
| `related-objects` | Emitted once on mount with a live ref to the fetched related objects. |
| `calculated-objects` | Emitted once on mount with a live ref to the fetched calculated objects. |
| `filtered` | Emitted once on mount with a live ref to the active-filter list (`filter.state.addedFilters`). |
| `query-change` | Emitted once on mount with a live ref to the current route query. |
| `hide-filter-form` | Forwarded from FilterGroup when a filter form popover should close. |
| `clear-scope` | Emitted with `{ name, keys }` when the reader clears a `params` key declared through the `scopes` prop. The prop is left unchanged: the caller removes `keys` from `params`, which removes the scope from the request and the constraints band. |

[Full event reference](/v3/reference/api/vue/ViewList/events.md)

## Source

`client/lib/views/ViewList.vue`