VueList Props

The VueList component is the main container that manages state, data fetching, and provides context to all child components.

Props

endpoint

string

API endpoint URL for fetching data. This is passed to the request handler as part of the context.

<VueList endpoint="/api/users">
  <!-- ... -->
</VueList>

meta

any

Additional request payload to include with every request. The request handler will receive this in the context object.

<VueList 
  endpoint="/api/users"
  :meta="{ teamId: 123, includeInactive: false }"
>
  <!-- ... -->
</VueList>

filters

object

Filter object that is reactive. Use v-model:filters for two-way binding. When filters change, the list automatically refetches data and resets to page 1.

<script setup>
import { ref } from 'vue'

const filters = ref({
  status: 'active',
  role: null
})
</script>

<template>
  <VueList 
    endpoint="/api/users"
    v-model:filters="filters"
  >
    <!-- ... -->
  </VueList>
</template>

page

number

default:"1"

Initial page number to load. This is only the initial value - the actual page state is managed internally by the component.

<VueList endpoint="/api/users" :page="2">
  <!-- ... -->
</VueList>

perPage

number

default:"25"

Number of items to fetch per page. This is the initial value - the actual state is managed internally.

<VueList endpoint="/api/users" :per-page="50">
  <!-- ... -->
</VueList>

sortBy

string

Column/field name to sort by initially. The actual sort state is managed internally.

<VueList endpoint="/api/users" sort-by="created_at">
  <!-- ... -->
</VueList>

sortOrder

'asc' | 'desc'

default:"'desc'"

Initial sort direction. Must be either 'asc' (ascending) or 'desc' (descending).

<VueList 
  endpoint="/api/users" 
  sort-by="name"
  sort-order="asc"
>
  <!-- ... -->
</VueList>

string

Initial search query. The actual search state is managed internally.

<VueList endpoint="/api/users" search="john">
  <!-- ... -->
</VueList>

attrs

array

List of attribute names to display in the list. Can be an array of strings or objects. If not provided, keys from the first response item will be used.

<!-- Simple array of strings -->
<VueList 
  endpoint="/api/users"
  :attrs="['name', 'email', 'created_at']"
>
  <!-- ... -->
</VueList>

<!-- Array of objects for more control -->
<VueList 
  endpoint="/api/users"
  :attrs="[
    { name: 'name', label: 'Full Name' },
    { name: 'email', label: 'Email Address' },
    { 
      name: 'address',
      label: 'Address',
      attrs: ['street', 'city', 'zip']
    }
  ]"
>
  <!-- ... -->
</VueList>

Show Attribute Object Structure

When using objects in the attrs array:

name (string, required): The field name
label (string): Display label (auto-generated if not provided)
attrs (array): Nested attributes for complex objects

requestHandler

function

Custom request handler function for this specific list. Overrides the global request handler defined in plugin options.

<script setup>
const customRequestHandler = async (requestData) => {
  const response = await fetch('/api/custom-endpoint', {
    method: 'POST',
    body: JSON.stringify(requestData)
  })
  const data = await response.json()
  return {
    items: data.results,
    count: data.totalCount
  }
}
</script>

<template>
  <VueList 
    endpoint="/api/users"
    :request-handler="customRequestHandler"
  >
    <!-- ... -->
  </VueList>
</template>

version

string | number

default:"1"

Version identifier for the list configuration. Used by the state manager to identify when configuration changes and clean up stale states.

<VueList 
  endpoint="/api/users"
  :version="2"
>
  <!-- ... -->
</VueList>

Increment the version number when you make significant changes to the list configuration, such as changing filters or attributes.

hasPaginationHistory

boolean

default:"true"

Enable pagination history in the URL. When enabled, the current page number is added to the URL as a query parameter.

<!-- URL will include ?page=2, ?page=3, etc. -->
<VueList 
  endpoint="/api/users"
  :has-pagination-history="true"
>
  <!-- ... -->
</VueList>

<!-- URL won't change -->
<VueList 
  endpoint="/api/users"
  :has-pagination-history="false"
>
  <!-- ... -->
</VueList>

paginationMode

'pagination' | 'loadMore'

default:"'pagination'"

Pagination mode to use:

'pagination': Standard pagination with page numbers
'loadMore': Load more button that appends items to the existing list

<!-- Standard pagination -->
<VueList 
  endpoint="/api/users"
  pagination-mode="pagination"
>
  <VueListPagination />
</VueList>

<!-- Load more mode -->
<VueList 
  endpoint="/api/posts"
  pagination-mode="loadMore"
>
  <VueListLoadMore />
</VueList>

Events

@onItemSelect

(newSelection: array, oldSelection: array) => void

Emitted when the selection changes.

<VueList 
  endpoint="/api/users"
  @on-item-select="(newSel, oldSel) => {
    console.log('Selected:', newSel)
  }"
>
  <!-- ... -->
</VueList>

@onResponse

(response: object) => void

Emitted when a response is received from the API, before items are set.

<VueList 
  endpoint="/api/users"
  @on-response="(response) => {
    console.log('Received:', response)
  }"
>
  <!-- ... -->
</VueList>

@afterPageChange

(response: object) => void

Emitted after a page change in pagination mode (not in loadMore mode).

<VueList 
  endpoint="/api/users"
  @after-page-change="(response) => {
    console.log('Page changed:', response)
  }"
>
  <!-- ... -->
</VueList>

@afterLoadMore

(response: object) => void

Emitted after loading more items in loadMore mode.

<VueList 
  endpoint="/api/posts"
  pagination-mode="loadMore"
  @after-load-more="(response) => {
    console.log('Loaded more:', response)
  }"
>
  <!-- ... -->
</VueList>

Slot Props

The default slot receives a scope object with all the list state and methods:

<VueList endpoint="/api/users" v-slot="{ items, count, isLoading, refresh }">
  <div>
    <p>Total: {{ count }}</p>
    <p v-if="isLoading">Loading...</p>
    
    <div v-for="item in items" :key="item.id">
      {{ item.name }}
    </div>
    
    <button @click="refresh">Refresh</button>
  </div>
</VueList>

Show Available Slot Props

items

array

Current array of items

count

number

Total count of items

response

object

Full response object from the API

isLoading

boolean

Whether data is currently being fetched

isInitialLoading

boolean

Whether this is the initial load

selection

array

Currently selected items

error

any

Error object if request failed

serializedAttrs

array

Processed attributes with labels

isEmpty

boolean

Whether the items array is empty

context

object

Current context object

refresh

function

Function to refresh the list data

Exposed Methods

The component exposes methods via template refs:

<script setup>
import { ref } from 'vue'

const listRef = ref()

function goToPage3() {
  listRef.value.setPage(3)
}

function refreshList() {
  listRef.value.refresh()
}
</script>

<template>
  <VueList ref="listRef" endpoint="/api/users">
    <!-- ... -->
  </VueList>
</template>

Show Exposed Methods and State

items

ref<array>

Reactive reference to items array

response

ref<object>

Reactive reference to API response

isLoading

ref<boolean>

Reactive reference to loading state

error

ref<any>

Reactive reference to error state

count

ref<number>

Reactive reference to total count

selection

ref<array>

Reactive reference to selection

setPage

(page: number) => void

Navigate to a specific page

setPerPage

(perPage: number) => void

Change items per page

setSort

({ by: string, order: string }) => void

Change sort configuration

setSearch

(query: string) => void

Update search query

setSelection

(items: array) => void

Update selected items

refresh

(context?: object) => void

Refresh the current page data

loadMore

() => void

Load more items (only in loadMore mode)

Core

Component Props

Props

Events

Slot Props

Exposed Methods

Build docs developers (and LLMs) love

Core

Component Props

​Props

​Events

​Slot Props

​Exposed Methods

Build docs developers (and LLMs) love

Props

Events

Slot Props

Exposed Methods