TanStack, Told Through the Green Lantern Corps

The night the ring chose me

A few years into building frontends, I had a dashboard that paged me at 2 a.m. Not because the server was down. Because of a useEffect with four dependencies, a race condition between two fetches, and a loading spinner that sometimes never went away. I fixed it by adding another useEffect. That made it worse. I added a useRef to “track if it’s the first render.” I am not proud of this.

That night I understood something every Green Lantern recruit learns on their first flight to Oa: raw power without discipline doesn’t make you a hero. It makes you a hazard to yourself and everyone near you.

A Green Lantern’s ring doesn’t do the thinking for you. It doesn’t hand you a finished construct. It takes your will — your intent, clearly formed — and gives it shape with total precision. Sloppy will gets you a wobbly, half-formed energy fist. Disciplined will gets you Hal Jordan building a working engine mid-flight.

That’s exactly what TanStack is. Not a framework that thinks for you — Redux, Next.js, whatever opinionated thing you’re used to, which hand you a finished shape. TanStack is headless. It’s a ring. It gives you raw, terrifyingly well-engineered power — caching, routing, virtualization, form state — and expects you to bring the will: the markup, the styling, the judgment. That’s why it rewards people who actually understand what they’re doing, and punishes people copy-pasting without reading. Same as a ring in untrained hands.

This is the guide I wish someone had handed me that night — Query, Router, Table, Form, and Virtual, explained the way the Corps would explain a power ring to a new recruit: here’s what it actually does, here’s the oath you need to take seriously, and here’s what happens when you ignore it.

---

The oath every TanStack library shares

Before assigning you a corps, every recruit hears the same doctrine, because every ring — green, blue, orange, indigo — draws from the same source. TanStack’s source is three rules, and once you internalize them, every library in the family stops feeling new:

1. Headless. No component ships with opinions about your markup or your CSS. You get the logic (sorting, caching, routing, validation) and you build the construct yourself.
2. Type-safe by construction, not by convention. If you’re on TypeScript, these libraries are built so the compiler catches your mistakes before your users do — inferred types flow from your schema all the way to your JSX.
3. Framework-agnostic at the core. The same engine powers React, Vue, Solid, and Svelte adapters. You’re not learning “a React thing.” You’re learning a ring that happens to have a React glove.

Keep those three in your head. Every weird API decision you’re about to see exists because of one of them.

---

TanStack Query — the Blue Lantern of Hope

In the mythos, the Blue Lanterns draw their power from hope — and their light only burns in the presence of a Green Lantern’s will nearby. On its own, hope can curdle into naivety. Paired with will, it’s one of the strongest forces in the universe.

That’s @tanstack/react-query, almost exactly. Hope is “the data will come back, and when it’s stale, we’ll quietly go get a fresher copy without making the user stare at a spinner they’ve already seen.” Naive hope is what you had before — useEffect + fetch + a loading boolean you reset by hand, with no idea whether the data in front of the user is five seconds old or five minutes old.

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

function UserProfile({ userId }: { userId: string }) {
  const { data, isPending, isError, error } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 60_000, // "trust this data for 60s before quietly refetching"
  });

  if (isPending) return <Spinner />;
  if (isError) return <ErrorBanner message={error.message} />;

  return <Profile user={data} />;
}

Notice what’s missing: no useState for the data, none for loading, none for errors, no cleanup function to avoid setting state on an unmounted component. The queryKey is the whole trick — it’s not just an ID, it’s the cache’s address for this exact piece of data. Change any part of it, and Query treats it as a different thing to fetch and cache separately.

function useUpdateUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (payload: UpdateUserPayload) => updateUser(payload),
    onSuccess: (_data, variables) => {
      // tell the Corps: this piece of hope is now out of date, go refresh it
      queryClient.invalidateQueries({ queryKey: ['user', variables.userId] });
    },
  });
}

That invalidateQueries call is the whole mental model in one line: you’re not manually syncing state across five components that all show the same user. You’re saying “this is stale now,” and every component subscribed to that queryKey, anywhere in the tree, refetches on its own. No prop drilling, no context, no “pass a refetch callback down three levels.”

The oath you have to actually keep: your queryKey must include every variable your queryFn depends on. Forget to include a filter or a page number in the key, and you get the single most common Query bug in existence — stale data silently served because the cache thinks nothing changed. This isn’t a library bug. It’s the Blue Lantern rule: hope without discipline becomes a lie you tell yourself.

Install the React Query Devtools early, not when something breaks:

import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
// <ReactQueryDevtools initialIsOpen={false} />

It shows you every cached query, its staleness, and its last fetch — the closest thing to X-ray vision for “why is my UI showing old data.”

---

TanStack Router — the Green Lantern of Will

Will is precision. A Green Lantern doesn’t wish a wall into existence — they will it, exactly, down to the rivets, because sloppy intent produces a construct that collapses under pressure. That’s the entire pitch of @tanstack/react-router next to React Router: it refuses to let your routing be vague.

import { createFileRoute } from '@tanstack/react-router';
import { z } from 'zod';

const searchSchema = z.object({
  page: z.number().catch(1),
  status: z.enum(['open', 'closed']).catch('open'),
});

export const Route = createFileRoute('/tickets/')({
  validateSearch: searchSchema,
  loaderDeps: ({ search }) => ({ page: search.page, status: search.status }),
  loader: ({ deps }) => fetchTickets(deps),
  component: TicketsPage,
});

function TicketsPage() {
  const { page, status } = Route.useSearch(); // fully typed, guaranteed valid
  const tickets = Route.useLoaderData();       // typed as whatever fetchTickets returns
  return <TicketList tickets={tickets} page={page} status={status} />;
}

Two things here would be runtime landmines in most routers and are compile-time guarantees here. First, useSearch() isn’t URLSearchParams soup you parse by hand and hope nobody passes ?status=banana — validateSearch rejects or coerces bad input before your component ever sees it. Second, Route.useLoaderData() isn’t any — TypeScript knows exactly what your loader returns, because the router traced the types through for you.

Navigating is the same discipline:

const navigate = Route.useNavigate();

navigate({
  to: '/tickets',
  search: (prev) => ({ ...prev, page: prev.page + 1 }),
});

Try passing a to that doesn’t exist, or a search shape that doesn’t match that route’s schema, and your editor turns red before you ever hit save. That’s not a nice-to-have. That’s the Book of Oa for your URL space: you cannot construct a route your will didn’t actually form correctly.

The oath: loaders run before your component renders, which means your data-fetching waterfall — the thing that made my 2 a.m. dashboard a nightmare — mostly disappears, because the router fetches in parallel with code-splitting instead of your component tree doing it one useEffect at a time, top to bottom, like a bucket brigade.

---

TanStack Table — the Orange Lantern of Avarice

There is exactly one Orange Lantern — Larfleeze — and his entire power is hoarding. Not sharing, not delegating, just absolute, obsessive ownership and organization of everything orange light has ever touched. It’s not a flattering power. It is, however, exactly what you want from something whose entire job is to take ten thousand rows of data and make you the sole, absolute authority over how they’re sorted, filtered, grouped, and paginated.

@tanstack/react-table renders nothing. That trips people up every time — “where’s my <Table> component?” There isn’t one. It gives you the hoard’s logic and makes you build the hoard’s display.

import {
  useReactTable,
  getCoreRowModel,
  getSortedRowModel,
  getFilteredRowModel,
  createColumnHelper,
} from '@tanstack/react-table';

const columnHelper = createColumnHelper<Ticket>();

const columns = [
  columnHelper.accessor('id', { header: 'ID' }),
  columnHelper.accessor('title', { header: 'Title' }),
  columnHelper.accessor('status', {
    header: 'Status',
    cell: (info) => <StatusBadge status={info.getValue()} />,
  }),
];

function TicketsTable({ data }: { data: Ticket[] }) {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
  });

  return (
    <table>
      <thead>
        {table.getHeaderGroups().map((hg) => (
          <tr key={hg.id}>
            {hg.headers.map((header) => (
              <th key={header.id} onClick={header.column.getToggleSortingHandler()}>
                {flexRender(header.column.columnDef.header, header.getContext())}
              </th>
            ))}
          </tr>
        ))}
      </thead>
      <tbody>
        {table.getRowModel().rows.map((row) => (
          <tr key={row.id}>
            {row.getVisibleCells().map((cell) => (
              <td key={cell.id}>{flexRender(cell.column.columnDef.cell, cell.getContext())}</td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

That’s more code than <Table data={data} /> from some component library, on purpose. You own every <th>, every <td>, every bit of markup — which means you can put that table inside a card, a dark theme, a mobile card-list layout on small screens, whatever your design actually needs, without fighting someone else’s CSS specificity. The “row model” functions you plug in (getSortedRowModel, getFilteredRowModel, getPaginationRowModel, getGroupedRowModel) are opt-in on purpose — you only pay for the hoarding logic you actually use.

The oath: because Table renders nothing, accessibility is entirely on you — correct <th scope="col">, aria-sort, keyboard-navigable sort toggles. Larfleeze doesn’t hand you a well-organized vault. He hands you the power to build one; a messy one is still possible, and it’s your fault if it happens.

---

TanStack Form — the Indigo Tribe of Compassion

The Indigo Tribe is the strangest corps in the mythos — their light is compassion, and they mostly recruit villains, because compassion is the thing that reaches people other lights can’t. That’s an oddly perfect metaphor for form libraries, because forms are where your users are at their most human: typos, hesitation, a phone number with the wrong number of digits, a required field they genuinely didn’t notice.

@tanstack/react-form is built around meeting the user where they are instead of yelling “INVALID” the second a field loses focus.

import { useForm } from '@tanstack/react-form';
import { z } from 'zod';

function SignupForm() {
  const form = useForm({
    defaultValues: { email: '', password: '' },
    onSubmit: async ({ value }) => {
      await signup(value);
    },
  });

  return (
    <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
      <form.Field
        name="email"
        validators={{
          onChange: z.string().email('That doesn\'t look like an email yet'),
        }}
      >
        {(field) => (
          <>
            <input
              value={field.state.value}
              onBlur={field.handleBlur}
              onChange={(e) => field.handleChange(e.target.value)}
            />
            {field.state.meta.isTouched && field.state.meta.errors.length > 0 && (
              <span className="error">{field.state.meta.errors.join(', ')}</span>
            )}
          </>
        )}
      </form.Field>

      <form.Subscribe selector={(state) => state.canSubmit}>
        {(canSubmit) => <button disabled={!canSubmit}>Create account</button>}
      </form.Subscribe>
    </form>
  );
}

The detail worth sitting with is isTouched. Compassion isn’t “never show an error” — it’s timing the error so it lands when it’s actually useful. Showing “invalid email” while the user is three characters into typing it isn’t honesty, it’s just rude. TanStack Form makes per-field, per-event (onChange, onBlur, onSubmit) validation timing a first-class option instead of a useEffect hack, and form.Subscribe means only the components that depend on a given slice of form state re-render — your whole form doesn’t repaint because one checkbox changed.

The oath: validators are composable with Zod, Valibot, or anything implementing the standard schema spec — the same schema you already wrote for your API or your router’s validateSearch can usually be reused here. Writing three separate validation schemas for the same shape is a sign you skipped the oath, not a sign the library is incomplete.

---

TanStack Virtual — conserving the battery

Every ring runs on a power battery, and even Green Lanterns need to return to a battery before it drains to nothing. Materializing every construct you can imagine, all at once, forever, isn’t heroism — it’s how you end up stranded in deep space with a dead ring. The disciplined move is to manifest only what you need, exactly when you need it.

@tanstack/react-virtual is that discipline applied to a 50,000-row list. Rendering 50,000 real DOM nodes is how you drain the browser’s battery to zero. Virtual renders only the rows currently in (or near) the viewport, and recycles the rest.

import { useVirtualizer } from '@tanstack/react-virtual';
import { useRef } from 'react';

function BigList({ items }: { items: string[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 48, // px per row
    overscan: 8,            // render a few extra rows above/below the viewport
  });

  return (
    <div ref={parentRef} style={{ height: 600, overflow: 'auto' }}>
      <div style={{ height: virtualizer.getTotalSize(), position: 'relative' }}>
        {virtualizer.getVirtualItems().map((virtualRow) => (
          <div
            key={virtualRow.key}
            style={{
              position: 'absolute',
              top: 0,
              transform: `translateY(${virtualRow.start}px)`,
              height: virtualRow.size,
            }}
          >
            {items[virtualRow.index]}
          </div>
        ))}
      </div>
    </div>
  );
}

getTotalSize() fakes the full scrollable height so the scrollbar behaves like all 50,000 rows exist, while getVirtualItems() only ever returns the handful currently worth rendering. overscan is your safety margin — render a few extra rows outside the viewport so fast scrolling doesn’t show blank flashes while new rows mount.

The oath: this only works cleanly when rows are a predictable, mostly-fixed height. Wildly variable row heights need measureElement to correct the estimate after the fact, and skipping that step is the single most common reason people say “virtualization feels janky” — they skipped reporting the real size back to the ring.

---

Pair Query + Router, and the whole thing clicks

The real “oh, that’s why this exists” moment is combining Router’s loaders with Query:

export const Route = createFileRoute('/tickets/$ticketId')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData({
      queryKey: ['ticket', params.ticketId],
      queryFn: () => fetchTicket(params.ticketId),
    }),
  component: TicketPage,
});

function TicketPage() {
  const { ticketId } = Route.useParams();
  // same queryKey → instantly served from cache, no waterfall, no duplicate fetch
  const { data } = useQuery({
    queryKey: ['ticket', ticketId],
    queryFn: () => fetchTicket(ticketId),
  });
  return <TicketDetail ticket={data} />;
}

The route’s loader pre-warms the exact same cache entry the component then reads — Will and Hope, charged from the same battery. Navigate to this route and the data is already there before the component mounts; navigate away and back within the staleTime window and it’s instant, no spinner, no refetch. This is the pattern that actually killed my waterfall dashboard — not a bigger useEffect, a battery that was already charged before the page needed it.

---

What nobody tells new recruits

Every one of these libraries will feel like more code than the opinionated alternative for the first week. A pre-styled table component really is less code than wiring useReactTable by hand. A simpler router really does need less setup than a schema-validated one.

That’s the actual trade, and it’s the same one every Green Lantern makes the day they accept the ring: you give up the comfort of something else deciding for you, in exchange for exact control when it actually matters — the week your table needs to be virtualized and sortable and accessible and match a design system nobody else’s component library was ever going to match.

Power rings don’t suit everyone. If your app is three pages and a contact form, you don’t need a corps — go build it with useState and be happy. But the day your dashboard pages you at 2 a.m. over a fetch waterfall nobody can explain, you’ll understand exactly why some recruits, once the ring chooses them, never go back to flying without one.