Skip to main content

​
Installation

The VueList plugin must be installed in your Vue 3 application to register all components globally. 
import { createApp } from 'vue'
import VueList from '@7span/vue-list'
import App from './App.vue'

const app = createApp(App)

app.use(VueList, {
  // Plugin options
})

app.mount('#app')

​
Plugin Options

The plugin accepts a configuration object with the following options:
​
componentPrefix
string
default:"''"
Prefix to add to all VueList component names. For example, if you set componentPrefix: 'My', components will be registered as MyVueList, MyVueListItems, etc.
app.use(VueList, {
  componentPrefix: 'My'
})
​
requestHandler
function
required
A global request handler function that fetches data for all VueList instances. This function receives request data and must return a Promise that resolves with an object containing items and count.
app.use(VueList, {
  requestHandler: async (requestData) => {
    const response = await fetch(`/api${requestData.endpoint}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(requestData)
    })
    
    const data = await response.json()
    
    return {
      items: data.items,
      count: data.total
    }
  }
})
​
stateManager
object
Custom state manager for persisting list state across navigation. Useful for maintaining pagination, search, and filter state.
app.use(VueList, {
  stateManager: {
    init: (context) => {
      // Initialize or clean up state when list is created
    },
    set: (context) => {
      // Save state when it changes
      sessionStorage.setItem(
        `vuelist-${context.endpoint}`,
        JSON.stringify(context)
      )
    },
    get: (context) => {
      // Retrieve saved state
      const saved = sessionStorage.getItem(`vuelist-${context.endpoint}`)
      return saved ? JSON.parse(saved) : null
    }
  }
})

​
Registered Components

When the plugin is installed, the following components are registered globally:
  • VueList - Main list container
  • VueListItems - Items renderer
  • VueListPagination - Pagination controls
  • VueListSearch - Search input
  • VueListInitialLoader - Loading indicator during initial load
  • VueListLoader - Loading indicator during subsequent loads
  • VueListError - Error message display
  • VueListSummary - Results summary
  • VueListPerPage - Per page selector
  • VueListLoadMore - Load more button
  • VueListGoTo - Go to page input
  • VueListRefresh - Refresh button
  • VueListAttributes - Attribute column controls
  • VueListEmpty - Empty state display
All components can be prefixed using the componentPrefix option.

Build docs developers (and LLMs) love

Get started for freeTalk to us