Skip to main content
VueList is built with a headless component architecture — it handles all the data fetching, state management, and list logic for you, but doesn’t impose any UI styling. Instead, it provides a set of composable components that expose useful state and behaviors through slots.

​
Architecture

The component system follows a provider-consumer pattern:
  1. <VueList> - The root component that manages all state and provides it to child components
  2. Child components - Consume the state via Vue’s inject API and render UI based on that state
All child components automatically have access to the list’s internal state without needing to pass props manually. This makes composition simple and flexible.

​
Component categories

​
Core components

VueList

Root component that manages list state and API calls

VueListItems

Renders the list items with customizable slots

VueListPagination

Page-based navigation with customizable page links

VueListLoadMore

Infinite scroll with a load more button

VueListGoTo

Dropdown to jump to a specific page

​
Control components

VueListSearch

Search input with debouncing

VueListPerPage

Select how many items to show per page

VueListRefresh

Button to refresh the current data

VueListAttributes

Toggle visibility of table columns

​
Status components

VueListLoader

Shows loading state during data fetches

VueListInitialLoader

Shows loading state on first load only

VueListError

Displays API errors

VueListEmpty

Shows message when no items exist

VueListSummary

Displays count summary (showing X-Y of Z)

​
Basic example

<template>
  <VueList endpoint="products" :per-page="10">
    <VueListSearch />
    <VueListInitialLoader />
    <VueListError />
    
    <VueListItems #default="{ items }">
      <div v-for="item in items" :key="item.id">
        <h3>{{ item.name }}</h3>
        <p>{{ item.price }}</p>
      </div>
    </VueListItems>
    
    <VueListLoader />
    <VueListEmpty />
    <VueListPagination />
  </VueList>
</template>

​
Key principles

​
1. Headless by design

Components don’t render any styled UI by default. They provide default slots that you can override with your own markup and styling.

​
2. Use only what you need

You don’t have to use every component. Pick the ones that match your UI requirements.

​
3. Full styling control

Wrap components in your own elements, use Tailwind, Bootstrap, or any CSS framework. The components add minimal wrapper divs with class names for targeting.

​
4. Automatic state injection

Child components automatically access list state via Vue’s provide/inject. No manual prop passing required.

​
State injection

The <VueList> component provides these values to all child components:
  • items - Array of data items
  • count - Total count from API
  • isLoading - Current loading state
  • isInitialLoading - True only on first load
  • error - Error object if request failed
  • localPage - Current page number
  • localPerPage - Items per page
  • localSearch - Current search query
  • localSortBy - Current sort column
  • localSortOrder - Current sort direction
  • Methods: setPage, setPerPage, setSearch, setSort, refresh, loadMore

​
Next steps

VueList component

Learn about the root component and its props

Custom styling guide

See examples of styling components

Build docs developers (and LLMs) love

Get started for freeTalk to us