Loading states

VitNode gives every loading moment one indicator: a top progress bar for route navigation, a skeleton for a section that is still loading, and a spinner inside the button that started an action.

Navigation progress barCopy Anchor Link

During a client-side navigation, a slim bar moves across the top of the viewport while the current page, header, and sidebar stay on screen and usable. NavigationProgress from @vitnode/core/tanstack/pending draws it, and VitNodeRootProviders already mounts it, so an app gets it without extra code.

The bar follows the router's own lifecycle:

• It appears only when a navigation lasts longer than 150 ms, so fast navigations never flash.
• It finishes when the router commits the destination, including an error page, a not-found page, or the target of a redirect.
• A newer navigation that replaces a pending one keeps the same bar moving instead of restarting it.
• Preloading on hover, router.invalidate(), and TanStack Query refetches never start it.
• With prefers-reduced-motion, it fades in and out at full width instead of moving.

To keep the current page visible, the router never swaps it for a pending component during a navigation:

import { createRouter as createTanStackRouter } from '@tanstack/react-router'
import { RoutePendingSpinner } from '@vitnode/core/tanstack/pending'

export function getRouter() {
  return createTanStackRouter({
    routeTree,
    defaultPendingComponent: RoutePendingSpinner,
    defaultPendingMs: Infinity,
  })
}

defaultPendingComponent still matters: it is the Suspense fallback of a route that has no pendingComponent of its own.

To show your own UI during a navigation, read the same state the bar uses with useIsRouteNavigating().

Component skeletons with SuspenseCopy Anchor Link

For feature pages with multiple asynchronous queries, wrap content in React <Suspense> using VitNode's pre-built pending skeletons:

import { FeedPendingSkeleton } from '@vitnode/core/tanstack/pending'
import { Suspense } from 'react'

const NotesList = () => {
  // Asynchronously fetched notes
  return <div>Notes List</div>
}

const NotesPage = () => {
  return (
    <div className="container mx-auto max-w-3xl p-4">
      <Suspense fallback={<FeedPendingSkeleton rows={4} />}>
        <NotesList />
      </Suspense>
    </div>
  )
}

export default NotesPage

Pre-built skeleton shapesCopy Anchor Link

Import pre-built skeletons directly from @vitnode/core/tanstack/pending:

Customizing skeleton propsCopy Anchor Link

The table, feed, cards, form, auth and route skeletons accept every prop of RoutePendingSkeletonProps. The profile, discover, search and breadcrumb skeletons accept only className and label.

import { TablePendingSkeleton } from '@vitnode/core/tanstack/pending'
import { Suspense } from 'react'

// `AdminNotesTable` is your table, which suspends while its query loads.
const AdminNotesPage = () => {
  return (
    <Suspense
      fallback={
        <TablePendingSkeleton
          className="p-6"
          rows={8}
          withDescription={false}
        />
      }
    >
      <AdminNotesTable />
    </Suspense>
  )
}

export default AdminNotesPage

Keep data on screen during refetchesCopy Anchor Link

A background refetch should never blank content that is already loaded. Show a skeleton only for the first load, which is isPending, never isFetching. For a query keyed on a search term, a filter, or a page, keep the previous result while the next one loads and mark it as busy:

import { keepPreviousData, useQuery } from '@tanstack/react-query'
import { FeedPendingSkeleton } from '@vitnode/core/tanstack/pending'
import { cn } from 'cn'

// `notesQueryOptions` is your own query helper, keyed on the search term.
const NotesSearch = ({ search }: { search: string }) => {
  const query = useQuery({
    ...notesQueryOptions({ search }),
    placeholderData: keepPreviousData,
  })

  if (query.isPending) return <FeedPendingSkeleton withDescription={false} />

  return (
    <ul
      aria-busy={query.isFetching}
      className={cn(query.isPlaceholderData && 'opacity-60')}
    >
      {query.data?.map(note => <li key={note.id}>{note.title}</li>)}
    </ul>
  )
}

Show action progress on the buttonCopy Anchor Link

Submissions and mutations show their progress on the control that started them. Pass isLoading to Button: it disables the button, swaps the label for a spinner without changing the width, and sets aria-busy. AutoForm and ConfirmAction already do this for their submit buttons.

import { Button } from '@vitnode/core/components/ui/button'
import { useMutation } from '@tanstack/react-query'

// `deleteNote` is your own API call. In a real handler, also invalidate the
// notes query and show a toast in `onSuccess`.
const DeleteNoteButton = ({ id }: { id: number }) => {
  const mutation = useMutation({ mutationFn: deleteNote })

  return (
    <Button
      isLoading={mutation.isPending}
      onClick={() => mutation.mutate(id)}
      variant="destructive"
    >
      Delete
    </Button>
  )
}

While the action runs, also disable any other control that would conflict with it, such as Reject next to a pending Approve.