---
url: "https://vueda.dev/v3/reference/api/js/use/useViewList.md"
title: "use/useViewList"
---

# use/useViewList

## Overview

Provides all reactive state and behaviour for a paginated, sortable,
searchable Django model list view. Returns sub-grouped reactive state that a custom
shell component binds to directly, without re-implementing route synchronization,
preference persistence, or the action/selection machinery.

The view name `"list"` is a fixed convention throughout this composable: it maps to
the Django REST Framework list action, the client-side route `action` param, and the
model config view key. This is intentional and not a configurable option.

## Examples

```vue
<script setup>
import { useViewList } from "@vueda/use/useViewList.js";
import { useSlotNameResolver } from "@vueda/use/useSlotNameResolver.js";
import { useSlots } from "vue";

const props = defineProps({ app: { type: String, required: true }, model: { type: String, required: true } });
const { modelConfig, list, actions, search, sort, columns, pagination, filter } = useViewList(props);
const slots = useSlots();
const bulkActionButtonSlotName = useSlotNameResolver(["bulk-action-button", "button"]);
</script>
```

```html
<objects-grid
    :fields="list.computedFieldObjects"
    :loading="list.loading"
    :objects-in-order="list.instanceList.state.objectsInOrder"
    :related-objects="list.instanceList.state.relatedObjects"
    :calculated-objects="list.instanceList.state.calculatedObjects"
    :field-props="{ pkKey: modelConfig.info?.pk, modelInfo: modelConfig.info, modelConfig: modelConfig.config }"
    :sortables="sort.sorting.state.sortables"
    :sorted="sort.sorting.state.sorted"
    @update:sorted="sort.sorting.updateSorted"
    @update:is-table="sort.isTable = $event"
/>
```

```html
<pagination-footer
    v-if="pagination.paginateInfo?.totalRecords > 0"
    v-model:current-page="list.listState.currentPage"
    v-model:per-page="list.listState.perPage"
    :loading="list.instanceList.state.loading"
    :rows="pagination.paginateInfo?.perPage"
    :total-records="pagination.paginateInfo?.totalRecords"
    :is-table="sort.isTable"
    :page-size-options="pageSizeOptions"
    :show-total-record-num="modelConfig.config?.showTotalRecordNum && showTotalRecordNum"
/>
```

```html
<filter-group
    v-model="filter.state.addedFilters"
    :app="props.app"
    :model="props.model"
    :view="'list'"
    :error="list.instanceList.state.error"
    :errored="list.instanceList.state.errored"
    :filterables="filter.filterables"
    :filterable-details="filter.filterableDetails"
    :valid-filterables="filter.validFilterables"
/>
```

```html
<template v-for="actionName in actions.bulkActions" :key="actionName">
    <slot :name="bulkActionButtonSlotName.name" v-bind="actions.buttonSlotProps[actionName]">
        <link-model-view
            button
            :pk="actions.buttonSlotProps[actionName].selectedObjects"
            v-bind="omit(actions.buttonSlotProps[actionName], ['selectedObjects'])"
        />
    </slot>
</template>
```

```html
<slot name="search" v-bind="search.searchSlotProps">
    <InputGroup>
        <InputGroupInput
            :model-value="search.searchSlotProps.listSearch"
            name="search"
            placeholder="Search"
            type="search"
            @search="search.filterList"
            @update:model-value="search.searchSlotProps.updateListSearch"
        />
        <InputGroupButton @click="search.filterList">Search</InputGroupButton>
    </InputGroup>
</slot>
```

```html
<Select v-model="columns.columns" multiple>
    <SelectTrigger size="sm"><SelectValue>columns</SelectValue></SelectTrigger>
    <SelectContent>
        <SelectItem v-for="option in columns.columnOptions" :key="option.value" :value="option.value">
            {{ option.label }}
        </SelectItem>
    </SelectContent>
</Select>
```

## Methods

- [useViewList](/v3/reference/api/js/use/useViewList/functions/useViewList.md) - Extracts all reactive state and wiring for a Django model list view.

## Types

### [ViewListActionsGroup](/v3/reference/api/js/use/useViewList/types/ViewListActionsGroup.md)

### [ViewListColumnsGroup](/v3/reference/api/js/use/useViewList/types/ViewListColumnsGroup.md)

### [ViewListContext](/v3/reference/api/js/use/useViewList/types/ViewListContext.md)

### [ViewListFilterGroup](/v3/reference/api/js/use/useViewList/types/ViewListFilterGroup.md)

### [ViewListListGroup](/v3/reference/api/js/use/useViewList/types/ViewListListGroup.md)

### [ViewListOptions](/v3/reference/api/js/use/useViewList/types/ViewListOptions.md)

Required identification.

### [ViewListPaginationGroup](/v3/reference/api/js/use/useViewList/types/ViewListPaginationGroup.md)

### [ViewListScope](/v3/reference/api/js/use/useViewList/types/ViewListScope.md)

### [ViewListScopeDeclaration](/v3/reference/api/js/use/useViewList/types/ViewListScopeDeclaration.md)

### [ViewListScopeGroup](/v3/reference/api/js/use/useViewList/types/ViewListScopeGroup.md)

### [ViewListSearchGroup](/v3/reference/api/js/use/useViewList/types/ViewListSearchGroup.md)

### [ViewListSortGroup](/v3/reference/api/js/use/useViewList/types/ViewListSortGroup.md)

## Source

`client/lib/use/useViewList.js:1`