Skip to main content

​
Overview

When installing VueList with app.use(), you can pass an options object to customize its behavior. This page documents all available configuration options.
main.js
import { createApp } from 'vue'
import VueList from '@7span/vue-list'

const app = createApp(App)

app.use(VueList, {
  // Configuration options go here
  componentPrefix: '',
  requestHandler: (context) => { /* ... */ },
  stateManager: { /* ... */ }
})

app.mount('#app')

​
Options Reference

​
componentPrefix

​
componentPrefix
string
default:"''"
Prefix to add to all globally registered VueList components
Use this to avoid naming conflicts or follow your app’s naming conventions. Default value: 
componentPrefix: ''
Example: 
app.use(VueList, {
  componentPrefix: ''
})

// Components available as:
// <VueList>
// <VueListItems>
// <VueListPagination>
// etc.
The prefix is applied to all VueList components. Make sure to use the prefixed names consistently throughout your app.

​
Registered Components

With or without a prefix, the following components are registered:
Base NameWith Prefix "My"Purpose
VueListMyVueListMain container component
VueListInitialLoaderMyVueListInitialLoaderLoading state on first load
VueListLoaderMyVueListLoaderLoading state during fetches
VueListItemsMyVueListItemsRenders list items
VueListErrorMyVueListErrorError display
VueListPaginationMyVueListPaginationPagination controls
VueListSummaryMyVueListSummary”Showing X to Y of Z”
VueListPerPageMyVueListPerPagePer-page selector
VueListSearchMyVueListSearchSearch input
VueListLoadMoreMyVueListLoadMoreLoad more button
VueListGoToMyVueListGoToGo to page input
VueListRefreshMyVueListRefreshRefresh button
VueListAttributesMyVueListAttributesColumn visibility
VueListEmptyMyVueListEmptyEmpty state

​
requestHandler

​
requestHandler
function
required
The global function used to fetch data for all lists. Receives context object, returns Promise resolving to { items, count }
This is the most important configuration option - it defines how VueList fetches data from your API. Default value: 
requestHandler() {
  return new Promise((resolve) => {
    resolve({
      items: [],
      count: 0
    })
  })
}
Type signature: 
type RequestHandler = (context: {
  endpoint: string
  page: number
  perPage: number
  search: string
  sortBy: string
  sortOrder: 'asc' | 'desc'
  filters: object
  meta: any
  version: string | number
  attrSettings: object
  isRefresh: boolean
}) => Promise<{
  items: any[]
  count: number
}>
Example: 
import axios from 'axios'

app.use(VueList, {
  requestHandler(context) {
    const { endpoint, page, perPage, search, sortBy, sortOrder, filters } = context
    
    return axios
      .get(`/api/${endpoint}`, {
        params: {
          page,
          limit: perPage,
          search,
          sort: sortBy,
          order: sortOrder,
          ...filters
        }
      })
      .then(({ data }) => ({
        items: data.results,
        count: data.total
      }))
  }
})
The requestHandler must return a Promise that resolves to an object with items (array) and count (number). If your API uses different property names, map them in the handler.
Per-Component Override: Individual components can override the global requestHandler: 
<template>
  <VueList 
    endpoint="special" 
    :request-handler="customHandler"
  >
    <!-- ... -->
  </VueList>
</template>

<script setup>
const customHandler = async (context) => {
  // Custom logic for this list only
  return { items: [], count: 0 }
}
</script>
See also:

​
stateManager

​
stateManager
object
Optional state persistence layer with init(), get(), and set() methods
Enables saving and restoring list state across sessions or page refreshes. Default value: 
stateManager: {
  set() {},
  get() {},
  init() {}
}
Type signature: 
type StateManager = {
  init: (context: Context) => void
  get: (context: Context) => object | null
  set: (context: Context) => void
}
Example: 
app.use(VueList, {
  stateManager: {
    init(context) {
      // Clean up old versions
      const prefix = `vue-list--${context.endpoint}--`
      const currentKey = `${prefix}${context.version}`
      
      Object.keys(localStorage)
        .filter(key => key.startsWith(prefix) && key !== currentKey)
        .forEach(key => localStorage.removeItem(key))
    },
    
    set(context) {
      const key = `vue-list--${context.endpoint}--${context.version}`
      const state = {
        search: context.search,
        page: context.page,
        perPage: context.perPage,
        sortBy: context.sortBy,
        sortOrder: context.sortOrder,
        filters: context.filters,
        attrSettings: context.attrSettings
      }
      localStorage.setItem(key, JSON.stringify(state))
    },
    
    get(context) {
      const key = `vue-list--${context.endpoint}--${context.version}`
      try {
        const stored = localStorage.getItem(key)
        return stored ? JSON.parse(stored) : null
      } catch {
        return null
      }
    }
  }
})
Methods:
​
stateManager.init
function
Called once when component mounts. Use for cleanup of old states.
init(context: Context): void
​
stateManager.get
function
Called on mount to restore saved state. Return state object or null.
get(context: Context): object | null
​
stateManager.set
function
Called on every state change to persist the context.
set(context: Context): void
The stateManager is completely optional. Without it, list state exists only in memory and resets on page refresh.
See also:

​
Complete Example

Here’s a production-ready configuration with all options:
main.js
import { createApp } from 'vue'
import VueList from '@7span/vue-list'
import { ofetch } from 'ofetch'
import App from './App.vue'

const app = createApp(App)

// Helper for state management keys
function stateKey(endpoint, version) {
  return `vue-list--${endpoint}--${version}`
}

app.use(VueList, {
  // Add prefix to avoid naming conflicts
  componentPrefix: 'App',
  
  // Define how to fetch data
  async requestHandler(context) {
    const { endpoint, page, perPage, search, sortBy, sortOrder, filters, isRefresh } = context
    
    // Build sort parameter
    let sort
    if (sortBy && sortOrder) {
      sort = `${sortBy}:${sortOrder}`
    }
    
    try {
      // Fetch count and data in parallel
      const [count, data] = await Promise.all([
        ofetch(`/api/${endpoint}/count`, {
          params: { search, ...filters }
        }),
        ofetch(`/api/${endpoint}`, {
          params: { page, limit: perPage, search, sort, ...filters },
          cache: isRefresh ? 'no-cache' : 'default'
        })
      ])
      
      return {
        items: data,
        count: count
      }
    } catch (error) {
      console.error('Failed to fetch:', error)
      const err = new Error('Failed to load data')
      err.name = 'FetchError'
      throw err
    }
  },
  
  // Persist state to localStorage
  stateManager: {
    init(context) {
      // Clean up states from old versions
      const prefix = `vue-list--${context.endpoint}--`
      const current = stateKey(context.endpoint, context.version)
      
      Object.keys(localStorage)
        .filter(key => key.startsWith(prefix) && key !== current)
        .forEach(key => localStorage.removeItem(key))
    },
    
    set(context) {
      const key = stateKey(context.endpoint, context.version)
      const state = {
        search: context.search,
        page: context.page,
        perPage: context.perPage,
        sortBy: context.sortBy,
        sortOrder: context.sortOrder,
        filters: context.filters,
        attrSettings: context.attrSettings
      }
      
      try {
        localStorage.setItem(key, JSON.stringify(state))
      } catch (error) {
        console.warn('Failed to save list state:', error)
      }
    },
    
    get(context) {
      const key = stateKey(context.endpoint, context.version)
      
      try {
        const stored = localStorage.getItem(key)
        return stored ? JSON.parse(stored) : null
      } catch (error) {
        console.warn('Failed to load list state:', error)
        return null
      }
    }
  }
})

app.mount('#app')

​
TypeScript Support

For TypeScript projects, VueList exports types for all options:
main.ts
import { createApp } from 'vue'
import VueList from '@7span/vue-list'
import type { VueListOptions, Context } from '@7span/vue-list'

const app = createApp(App)

const options: VueListOptions = {
  componentPrefix: 'App',
  
  async requestHandler(context: Context) {
    return {
      items: [],
      count: 0
    }
  },
  
  stateManager: {
    init(context: Context) {},
    get(context: Context) { return null },
    set(context: Context) {}
  }
}

app.use(VueList, options)
app.mount('#app')

Build docs developers (and LLMs) love

Get started for freeTalk to us