Skip to main content

​
Overview

VueList is installed as a Vue plugin using app.use(). During installation, you can pass a configuration object that defines global behavior for all VueList instances in your application. The configuration consists of three main options:
  1. requestHandler - The function that fetches data from your API
  2. stateManager - Optional persistence layer for list state
  3. componentPrefix - Optional prefix for component names

​
Basic Configuration

Here’s a minimal configuration example:
main.js
import { createApp } from 'vue'
import VueList from '@7span/vue-list'
import axios from 'axios'
import App from './App.vue'

const app = createApp(App)

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.items,
        count: data.total
      }))
  }
})

app.mount('#app')

​
Complete Configuration

Here’s a full example with all available 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)

app.use(VueList, {
  // Add prefix to all VueList components
  componentPrefix: 'My',
  
  // Define how to fetch data
  async requestHandler(context) {
    const { endpoint, page, perPage, search, sortBy, sortOrder } = context
    
    const [count, items] = await Promise.all([
      ofetch(`/api/${endpoint}/count`),
      ofetch(`/api/${endpoint}`, {
        params: { page, limit: perPage, search }
      })
    ])
    
    return { items, count }
  },
  
  // Persist state to localStorage
  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}`
      const stored = localStorage.getItem(key)
      return stored ? JSON.parse(stored) : null
    }
  }
})

app.mount('#app')
The configuration you provide during app.use() is applied globally to all <VueList> components in your app. Individual components can override the requestHandler via props if needed.

​
Component Registration

When you install VueList, the following components are automatically registered globally:
  • <VueList> - Main container component
  • <VueListInitialLoader> - Loading state on first load
  • <VueListLoader> - Loading state during data fetches
  • <VueListItems> - Renders list items
  • <VueListError> - Displays error states
  • <VueListPagination> - Pagination controls
  • <VueListSummary> - Shows “Showing X to Y of Z”
  • <VueListPerPage> - Per-page selector
  • <VueListSearch> - Search input
  • <VueListLoadMore> - Load more button
  • <VueListGoTo> - Go to page input
  • <VueListRefresh> - Refresh button
  • <VueListAttributes> - Column visibility controls
  • <VueListEmpty> - Empty state
All components are prefixed with the componentPrefix option. If you set componentPrefix: 'My', components become <MyVueList>, <MyVueListItems>, etc.

​
Using with TypeScript

VueList is written in Vue 3 with full composition API support:
main.ts
import { createApp } from 'vue'
import VueList from '@7span/vue-list'
import type { VueListOptions } from '@7span/vue-list'
import App from './App.vue'

const app = createApp(App)

const options: VueListOptions = {
  requestHandler: async (context) => {
    // Your implementation
    return {
      items: [],
      count: 0
    }
  }
}

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

​
Next Steps

Request Handler

Learn how to implement the data fetching function

State Manager

Persist list state across sessions

All Options

Complete reference of all configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us