Docs/Data Components

Data Components

Components that wrap content with loading, pagination, or capture flows.

SparkAsync

Handles loading state, error display, and retry in one component. Pass an async loader; the component runs it and renders the right state.

<script setup>
import { ref } from 'vue';
import { SparkAsync, SparkButton } from '@katforge/spark';
import source from './SparkDemoAsync.vue?raw';

const players = [
   { id: 1, name: 'Ashen',  realm: 'Ember Reach' },
   { id: 2, name: 'Brimm',  realm: 'Ember Reach' },
   { id: 3, name: 'Cinder', realm: 'Ash Hollow'  },
   { id: 4, name: 'Ember',  realm: 'Ash Hollow'  },
];

const modes = [
   { value: 'ok',    label: 'Success' },
   { value: 'empty', label: 'Empty'   },
   { value: 'error', label: 'Error'   },
];

const mode = ref ('ok');

const watchMode = () => mode.value;

function load () {
   return new Promise ((resolve, reject) => {
      setTimeout (() => {
         if (mode.value === 'error') return reject (new Error ('Could not reach the realm shard'));
         if (mode.value === 'empty') return resolve ([]);
         resolve (players);
      }, 900);
   });
}
</script>

<template>
   <SparkDemoBox :source="source">
      <ClientOnly>
         <div class="space-y-5">
            <div class="flex items-center justify-between gap-4 flex-wrap">
               <span class="text-[11px] font-semibold uppercase tracking-wider text-white/40">Loader response</span>

               <div class="inline-flex items-center rounded-kf-md border border-white/10 bg-black/40 p-1" role="tablist">
                  <button
                     v-for="opt in modes"
                     :key="opt.value"
                     type="button"
                     role="tab"
                     :aria-selected="mode === opt.value"
                     :class="[ 'spark-demo-async-segment', { 'is-active': mode === opt.value } ]"
                     @click="mode = opt.value"
                  >
                     {{ opt.label }}
                  </button>
               </div>
            </div>

            <SparkAsync
               :load="load"
               :watch="watchMode"
               :keep-data="false"
            >
               <template #default="{ data, refresh }">
                  <div class="space-y-4">
                     <ul class="spark-demo-async-list rounded-kf-lg border border-white/10 bg-black/30 overflow-hidden divide-y divide-white/5">
                        <li v-for="p in data" :key="p.id" class="spark-demo-async-row flex items-center gap-4 px-4 py-3 transition-colors duration-150">
                           <span class="text-sm text-white/85 font-medium">{{ p.name }}</span>
                           <span class="text-xs text-white/40 flex-1">{{ p.realm }}</span>
                           <span class="text-[11px] text-white/30 font-mono">#{{ p.id }}</span>
                        </li>
                     </ul>

                     <div class="flex justify-end">
                        <SparkButton variant="ghost" @click="refresh">Refresh</SparkButton>
                     </div>
                  </div>
               </template>

               <template #empty="{ refresh }">
                  <div class="flex flex-col items-center justify-center gap-3 px-6 py-12 rounded-kf-lg border border-white/10 bg-black/30 text-center">
                     <div class="flex items-center justify-center w-12 h-12 rounded-full bg-white/5 text-white/40 mb-1 text-[1.5rem]">
                        <Icon name="lucide:inbox" />
                     </div>

                     <p class="text-sm font-semibold text-white/80">No players online</p>
                     <p class="text-xs text-white/40 mb-2">The realm is quiet. Try again in a moment.</p>

                     <SparkButton variant="ghost" @click="refresh">Check again</SparkButton>
                  </div>
               </template>

               <template #error="{ error, retry }">
                  <div class="flex flex-col items-center justify-center gap-3 px-6 py-12 rounded-kf-lg border border-white/10 bg-black/30 text-center">
                     <div class="spark-demo-async-state-glyph-error flex items-center justify-center w-12 h-12 rounded-full mb-1 text-[1.5rem]">
                        <Icon name="lucide:triangle-alert" />
                     </div>

                     <p class="text-sm font-semibold text-white/80">Couldn't load players</p>
                     <p class="text-xs text-white/40 mb-2">{{ error.message }}</p>

                     <SparkButton variant="ghost" @click="retry">Try again</SparkButton>
                  </div>
               </template>
            </SparkAsync>
         </div>
      </ClientOnly>
   </SparkDemoBox>
</template>

<style scoped>
@reference "~/assets/css/main.css";

.spark-demo-async-segment {
   @apply px-3 py-1.5 text-xs font-medium rounded-kf-sm text-white/50;
   @apply transition-colors duration-150 cursor-pointer;
}

.spark-demo-async-segment:hover:not(.is-active) {
   @apply text-white/80 bg-white/5;
}

.spark-demo-async-segment.is-active {
   @apply bg-white/10 text-white;
}

.spark-demo-async-row:hover {
   @apply bg-white/[0.03];
}

.spark-demo-async-state-glyph-error {
   background: color-mix(in srgb, var(--color-kf-error) 12%, transparent);
   color: var(--color-kf-error);
}
</style>

Vue

<template>
   <SparkAsync :load="loadUsers">
      <template #default="{ data, refresh }">
         <ul>
            <li v-for="user in data" :key="user.id">{{ user.name }}</li>
         </ul>
         <button class="kf-btn-ghost" @click="refresh">Reload</button>
      </template>
   </SparkAsync>
</template>

<script setup>
import { SparkAsync, useApi } from '@katforge/spark';

const api = useApi ();
const loadUsers = () => api.users.list ();
</script>

The default loading state is a centered brand spinner; the default error state shows the error message with a Retry button. Override either with the loading or error slot.

Vue

<SparkAsync :load="loadUsers">
   <template #loading>
      <div class="py-12 text-center text-kf-muted">Fetching users…</div>
   </template>

   <template #error="{ error, retry }">
      <div class="kf-card-glass p-4">
         <p class="text-kf-error mb-3">{{ error.message }}</p>
         <SparkButton variant="ghost" @click="retry">Try again</SparkButton>
      </div>
   </template>

   <template #default="{ data }">
      <UserTable :users="data" />
   </template>
</SparkAsync>

Re-fetching on dependency change

Pass any reactive source (or array of sources) to watch. The loader re-runs whenever the source changes. Combine with keepData (default true) to keep showing the previous result while the new one fetches, useful for filters and pagination.

Vue

<template>
   <SparkInput v-model="query" placeholder="Search…" />

   <SparkAsync :load="() => kf.search (query)" :watch="query">
      <template #default="{ data, loading }">
         <div :class="{ 'opacity-50': loading }">
            <SearchResult v-for="r in data" :key="r.id" :result="r" />
         </div>
      </template>
   </SparkAsync>
</template>

Manual mode and empty state

Set :immediate="false" to skip the auto-load on mount. Provide an empty slot to render when the loader resolves with an empty array.

Vue

<SparkAsync :load="loadReport" :immediate="false">
   <template #default="{ data, refresh }">
      <SparkButton v-if="!data" @click="refresh">Generate report</SparkButton>
      <ReportView v-else :report="data" />
   </template>
</SparkAsync>

<SparkAsync :load="() => kf.notifications.list ()">
   <template #empty="{ refresh }">
      <p class="text-kf-muted">No notifications yet.</p>
      <SparkButton variant="ghost" @click="refresh">Check again</SparkButton>
   </template>

   <template #default="{ data }">
      <NotificationRow v-for="n in data" :key="n.id" :notification="n" />
   </template>
</SparkAsync>

A fast API response can flash the spinner so briefly that the UI feels jittery. SparkAsync holds the loading state for at least minDuration ms (default 750) before settling. Set :min-duration="0" to opt out, or raise it for endpoints where a longer pause feels intentional.

Animated transitions

Every state change (loading → content, content → empty, error → loading on retry) animates with a subtle 200 ms fade + 4 px slide. SparkAsync wraps its rendered state in a single <div class="spark-async-frame"> so the transition has a stable element to animate. If you need a fragment-style render with no wrapper, drop down to useAsync ().

Props

Prop	Type	Default	Description
`load`	`() => Promise<T>`	—	Required. The async loader. Re-invoked on `refresh ()` and on `watch` source change
`immediate`	`boolean`	`true`	Run the loader on mount
`watch`	`WatchSource \| WatchSource[]`	—	Re-run the loader when any of these change
`keepData`	`boolean`	`true`	Keep showing previous data during a refresh until the new data arrives
`initial`	`T`	`null`	Initial value for `data` before the first load resolves
`minDuration`	`number`	`750`	Minimum milliseconds the loading state is held, even if the loader resolves sooner. `0` disables.

Slots

Slot	Props	Description
`default`	`{ data, refresh, loading, error }`	Rendered once data is available
`loading`	`{}`	Shown during the first load. Defaults to a centered brand spinner
`error`	`{ error, retry }`	Shown when the loader rejects and no data is available
`empty`	`{ refresh }`	Optional. Shown when `data` is an empty array

SparkAsyncPaged

SparkAsync's paginated sibling. Same loading, error, empty, and content states, plus an accumulated items array, a hasMore cursor, and IntersectionObserver-powered automatic page loading.

Use SparkAsyncPaged when the backend returns pages and the UI should append more as the user scrolls. For a single one-shot fetch, reach for SparkAsync.

<script setup>
import { SparkAsyncPaged, SparkSpinner, SparkButton } from '@katforge/spark';
import source from './SparkDemoAsyncPaged.vue?raw';

const REALMS = [ 'Ember Reach', 'Ash Hollow', 'Cinder Vale', 'Mire Spire' ];
const NAMES  = [
   'Ashen', 'Brimm', 'Cinder', 'Ember', 'Flint',  'Gloam',
   'Hollow', 'Ire', 'Jet',    'Kell',  'Lurk',   'Mire',
   'Nox',   'Onyx', 'Pyre',   'Quill', 'Riven',  'Soot',
   'Tarn',  'Umbra',
];

const PAGE_SIZE = 5;
const TOTAL     = NAMES.length;

const ALL = NAMES.map ((name, i) => ({
   id:     i + 1,
   name,
   realm:  REALMS [i % REALMS.length],
   rating: 1200 + ((i * 37) % 800),
}));

function loadPage (page) {
   const start = (page - 1) * PAGE_SIZE;
   const end   = start + PAGE_SIZE;
   const items = ALL.slice (start, end);

   return new Promise ((resolve) => {
      setTimeout (() => {
         resolve ({
            items,
            total:   TOTAL,
            hasMore: end < TOTAL,
         });
      }, page === 1 ? 900 : 600);
   });
}
</script>

<template>
   <SparkDemoBox :source="source">
      <ClientOnly>
         <SparkAsyncPaged :load="loadPage" :min-duration="900">
            <template #default="{ items, total, hasMore, loading, loadingMore, sentinelRef, refresh }">
               <div class="space-y-3">
                  <div class="flex items-center justify-between gap-4">
                     <span class="spark-demo-paged-count text-xs text-white/50">
                        Showing <strong>{{ items.length }}</strong> of {{ total }}
                     </span>

                     <SparkButton variant="ghost" :loading="loading" @click="refresh">Refresh</SparkButton>
                  </div>

                  <div class="spark-demo-paged-scroll rounded-kf-lg border border-white/10 bg-black/30 overflow-y-auto">
                     <ul class="divide-y divide-white/5">
                        <li
                           v-for="entry in items"
                           :key="entry.id"
                           class="spark-demo-paged-row grid items-center gap-4 px-4 py-3 grid-cols-[3rem_1fr_1fr_auto]"
                        >
                           <span class="text-[11px] text-white/30 font-mono tabular-nums">#{{ entry.id }}</span>
                           <span class="text-sm text-white/85 font-medium">{{ entry.name }}</span>
                           <span class="text-xs text-white/40">{{ entry.realm }}</span>
                           <span class="text-xs text-white/60 font-mono tabular-nums">{{ entry.rating }}</span>
                        </li>
                     </ul>

                     <div :ref="sentinelRef" class="h-px" />

                     <div v-if="loadingMore" class="spark-demo-paged-foot flex items-center justify-center gap-2 px-4 py-3 text-xs text-white/50 border-t border-white/5">
                        <SparkSpinner :size="16" />
                        <span>Loading more…</span>
                     </div>

                     <div v-else-if="!hasMore" class="spark-demo-paged-foot is-end flex items-center justify-center gap-2 px-4 py-3 text-xs text-white/50 border-t border-white/5">
                        End of leaderboard
                     </div>
                  </div>
               </div>
            </template>
         </SparkAsyncPaged>
      </ClientOnly>
   </SparkDemoBox>
</template>

<style scoped>
@reference "~/assets/css/main.css";

.spark-demo-paged-count strong {
   @apply text-white/85 font-semibold tabular-nums;
}

.spark-demo-paged-scroll {
   max-height: 18rem;

   /* Slim scrollbar */
   scrollbar-width: thin;
   scrollbar-color: rgba(255, 255, 255, 0.18) transparent;
}

.spark-demo-paged-scroll::-webkit-scrollbar {
   width: 8px;
}

.spark-demo-paged-scroll::-webkit-scrollbar-thumb {
   background: rgba(255, 255, 255, 0.14);
   border-radius: 999px;
   border: 2px solid transparent;
   background-clip: padding-box;
}

.spark-demo-paged-scroll::-webkit-scrollbar-thumb:hover {
   background: rgba(255, 255, 255, 0.28);
   background-clip: padding-box;
   border: 2px solid transparent;
}

.spark-demo-paged-row {
   /* Only transition background — `transition-colors` includes border-color,
    * which animates new rows' top borders through the default white before
    * settling on `divide-white/5`'s rgba(255,255,255,0.05). */
   transition: background-color 150ms ease;
}

.spark-demo-paged-row:hover {
   @apply bg-white/[0.03];
}

.spark-demo-paged-foot.is-end {
   @apply text-white/30 italic;
}
</style>

Scroll the list above. The sentinel at the end of the rows triggers loadMore () as soon as it enters the viewport, so the next page appends without a click. The "Loading more…" row appears between pages; the "End of leaderboard" row settles in once hasMore flips to false.

Loader contract

Your load function takes a 1-based page number and returns a PagedResult:

TypeScript

interface PagedResult <T> {
   items:    T [];
   hasMore:  boolean;
   total?:   number;
}

The component owns the accumulator: items is the flat list of everything loaded so far, not just the most recent page. Refreshes reset it; loadMore () appends.

Basic usage

Vue

<template>
   <SparkAsyncPaged
      :load="loadLeaderboardPage"
      :watch="query"
      :min-duration="1000"
   >
      <template #default="{ items, loadingMore, hasMore, sentinelRef }">
         <div class="kf-card !p-0 overflow-y-auto max-h-96">
            <LeaderboardRow
               v-for="entry in items"
               :key="entry.rank"
               :entry="entry"
            />

            <div :ref="sentinelRef" />

            <div v-if="loadingMore" class="flex justify-center py-3">
               <SparkSpinner :size="16" />
            </div>

            <div v-else-if="!hasMore" class="flex justify-center py-2">
               <p class="text-xs text-kf-muted">End of leaderboard</p>
            </div>
         </div>
      </template>

      <template #empty>
         <p class="text-kf-muted py-6 text-center">No players yet.</p>
      </template>
   </SparkAsyncPaged>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { SparkAsyncPaged, SparkSpinner, useApi } from '@katforge/spark';
import type { PagedResult } from '@katforge/spark';

const api   = useApi ();
const query = ref ('');

async function loadLeaderboardPage (page: number): Promise <PagedResult <Entry>> {
   const { entries, has_more, total } = await api.leaderboard.list ({ page, query: query.value });
   return { items: entries, hasMore: has_more, total };
}
</script>

sentinelRef is a function template-ref. Attach it to any element at the end of your list (typically an invisible <div />), and the component fires loadMore () whenever that element scrolls into view. No scroll handlers, no pixel math.

Resetting on filter / tab change

Pass a reactive source (or array of sources) to watch. The loader reruns for page 1, the accumulator resets, pagination starts over. Debounce search inputs yourself if you don't want a request per keystroke.

Vue

<SparkAsyncPaged
   :load="(page) => kf.users.search ({ q: query, tab: activeTab, page })"
   :watch="[ query, activeTab ]"
>…</SparkAsyncPaged>

Manual pagination

You don't have to use the observer. Omit the sentinel element and call loadMore () yourself, e.g. from a "Show more" button.

Vue

<SparkAsyncPaged :load="loadReports">
   <template #default="{ items, loadMore, loadingMore, hasMore }">
      <ReportCard v-for="r in items" :key="r.id" :report="r" />

      <SparkButton
         v-if="hasMore"
         variant="ghost"
         :disabled="loadingMore"
         @click="loadMore"
      >
         {{ loadingMore ? 'Loading…' : 'Show more' }}
      </SparkButton>
   </template>
</SparkAsyncPaged>

Like SparkAsync, the initial load holds the loading state for minDuration ms (default 750). Subsequent loadMore () appends don't — they should feel instant.

Props

Prop	Type	Default	Description
`load`	`(page: number) => Promise<PagedResult<T>>`	—	Required. Called with a 1-based page number.
`immediate`	`boolean`	`true`	Run the loader on mount
`watch`	`WatchSource \| WatchSource[]`	—	Reset pagination and refetch page 1 when any source changes
`initial`	`T[]`	`[]`	Seed `items` before the first fetch resolves
`minDuration`	`number`	`750`	Minimum ms the initial loading state is held. Page 1 only.
`sentinelMargin`	`string`	`'0px 0px 120px 0px'`	`rootMargin` for the IntersectionObserver

Slots

Slot	Props	Description
`default`	`{ items, total, page, hasMore, loading, loadingMore, error, refresh, loadMore, sentinelRef }`	Rendered once any data is available
`loading`	`{}`	First-load spinner. Defaults to a centered brand spinner
`error`	`{ error, retry }`	Shown when the initial load rejects and no items are present
`empty`	`{ refresh }`	Optional. Shown when the loader resolves with zero items

For full programmatic control, use usePagedAsync () directly.

SparkFeedback

Drop-in feedback collector for games and sites. Renders a translucent floating bubble in a screen corner that opaques on hover, opening a kind-tagged feedback modal (Bug / Idea / Praise / Other). Submits to the shared /v1/leads/feedback endpoint via the @katforge/api — bearer token is auto-forwarded for logged-in callers, so the server stamps user_id and player_id automatically. Guests can attach an optional reply-to email.

Pick a placement — the bubble pins to the corner of your viewport (try resting then hovering it). Pick "Inline" to render the trigger here in the demo.

<template>
   <SparkDemoBox :source="source">
      <div class="relative min-h-[12rem]">
         <div class="flex flex-col items-center gap-4 px-4 py-6 rounded-kf-lg border border-dashed border-white/[0.08] bg-gradient-to-b from-white/[0.02] to-white/[0.04]">
            <p class="text-center text-[0.8125rem] text-white/50 m-0 max-w-[32rem]">
               Pick a placement — the bubble pins to the corner of your viewport (try resting then hovering it). Pick "Inline" to render the trigger here in the demo.
            </p>

            <div class="inline-flex gap-1.5">
               <button
                  v-for="p in placements"
                  :key="p.value"
                  type="button"
                  :class="[ 'spark-demo-feedback-pick', { 'is-active': placement === p.value } ]"
                  @click="placement = p.value"
               >
                  {{ p.label }}
               </button>
            </div>
         </div>

         <ClientOnly>
            <SparkFeedback
               :key="placement"
               :source="Realms.katforge"
               :placement="placement"
               :label="placement === 'inline' ? 'Send feedback' : 'Feedback'"
            />
         </ClientOnly>
      </div>
   </SparkDemoBox>
</template>

<script setup>
import { ref } from 'vue';
import { Realms, SparkFeedback } from '@katforge/spark';
import source from './SparkDemoFeedback.vue?raw';

const placements = [
   { value: 'bottom-right', label: 'Bottom right' },
   { value: 'bottom-left',  label: 'Bottom left'  },
   { value: 'inline',       label: 'Inline'       },
];

const placement = ref ('bottom-right');
</script>

<style scoped>
.spark-demo-feedback-pick {
   padding: 0.375rem 0.75rem;
   font-size: 0.75rem;
   font-weight: 600;
   letter-spacing: 0.04em;
   text-transform: uppercase;
   border-radius: 999px;
   border: 1px solid rgba(255, 255, 255, 0.08);
   background: rgba(255, 255, 255, 0.04);
   color: rgba(255, 255, 255, 0.6);
   cursor: pointer;
   transition: color 150ms ease, background 150ms ease, border-color 150ms ease;
}

.spark-demo-feedback-pick:hover {
   color: rgba(255, 255, 255, 0.9);
   background: rgba(255, 255, 255, 0.08);
}

.spark-demo-feedback-pick.is-active {
   color: #fff;
   background: rgba(251, 146, 60, 0.18);
   border-color: rgba(251, 146, 60, 0.5);
}
</style>

Vue

<template>
   <RouterView />
   <SparkFlashContainer />

   <!-- One line at app root — the bubble lives over every page -->
   <SparkFeedback :source="Realms.stumper" />
</template>

<script setup>
import { Realms, SparkFeedback, SparkFlashContainer } from '@katforge/spark';
</script>

The source prop is typed against the Realms const so the right realm is always sent. Pass the value through Realms.<slug> for autocomplete and refactor safety — typos become compile errors instead of silently bad data on the server.

For navbars, set placement="inline" to render just the trigger so consumers can place it inside their existing layout:

Vue

<header class="navbar">
   <SparkLogo />
   <nav>…</nav>
   <SparkFeedback :source="Realms.katforge" placement="inline" label="Feedback" />
   <SparkUserMenu />
</header>

Pass context to attach app state for triage. The component stamps route with window.location.pathname automatically; pass route explicitly to override (e.g. when using a virtual router).

Vue

<SparkFeedback
   :source="Realms.stumper"
   :context="{
      mode: game.mode,
      difficulty: game.difficulty,
      session_score: game.score,
   }"
   :route="route.fullPath"
/>

For the storage shape, retention, and triage behavior, see the API endpoint reference.

Props

Prop	Type	Default	Description
`source`	`RealmSlug`	—	Required. Realm submitting the feedback.
`placement`	`'bottom-right' \| 'bottom-left' \| 'inline'`	`'bottom-right'`	`inline` renders only the trigger button, suitable for navbars.
`label`	`string`	`'Feedback'`	Trigger label. Shown inline; used as `aria-label` and revealed-on-hover label on the floating tab.
`context`	`Record<string, unknown>`	`{}`	Free-form metadata stored alongside the feedback.
`route`	`string`	`window.location.pathname`	Route override.
`palette`	`SparkPalette`	`palettes.ember`	Palette scoped to the modal.

Events

Event	Payload	Description
`submit`	`FeedbackKind`	Fires after a successful submission with the chosen kind (`'bug'`, `'idea'`, `'praise'`, `'other'`).

Behavior

Auth-aware. Logged-in users skip the email field — user_id and player_id come from the bearer token. Guests see an optional email field for follow-up.
Tab-style at rest. The floating trigger bulges past the viewport edge so only the inner half is visible. On hover or focus it slides fully into the viewport, opaques up, and reveals the label.
Per-kind color. Red for Bug, amber for Idea, pink for Praise, indigo for Other.
Rate limited. 5 submissions per minute per IP, mirroring the contact form throttle.

Imperative API

Mount one <SparkFeedback> at app root and any other Spark component (or your own code) can drive the modal via the useFeedback composable. SparkUserMenu's built-in Feedback menu item already does this.

TypeScript

import { useFeedback } from '@katforge/spark';

const feedback = useFeedback ();

feedback.value?.open ();          // open the modal
feedback.value?.open ('bug');     // preselect a kind
feedback.value?.close ();
feedback.value?.toggle ();

useFeedback () returns Ref<FeedbackHandle | null>. The ref is null until a <SparkFeedback> mounts somewhere in the app, so callers should hide their own affordance or fall back to a link when the value is null.

Realms enum

Spark ships a Realms const + matching RealmSlug type. Use it for source instead of hand-typing strings — autocomplete prevents typos, and the same list is enforced server-side.

TypeScript

import { Realms } from '@katforge/spark';

Realms.katforge   // 'katforge'
Realms.stumper    // 'stumper'
Realms.lextris    // 'lextris'
Realms.goblins    // 'goblins'
Realms.wc3stats   // 'wc3stats'
Realms.darkerdb   // 'darkerdb'

REALM_SLUGS is the runtime list (ReadonlyArray<RealmSlug>), useful for iteration or validation.

SparkScrollbar

Slim scroll container with the KATforge-styled scrollbar. Replaces the default browser scrollbar (which renders white on dark backgrounds across most platforms) with a low-contrast track and a brand-tinted thumb on hover. Used internally by SparkCombobox, SparkSelect, and SparkUserMenu; reach for it directly whenever you need a scrolling region inside dark Spark surfaces.

Default browser scrollbar

#1Inferno
#2Ember
#3Bellows
#4Crucible
#5Hearth
#6Pyre
#7Cinder
#8Spark
#9Tinder
#10Anvil
#11Forge
#12Smelter
#13Bloom
#14Slag
#15Quench
#16Temper
#17Rivet
#18Hammer
#19Mortar
#20Kiln
#21Foundry
#22Ironworks
#23Bellower
#24Striker
#25Quencher
#26Gilder
#27Smith
#28Wrought
#29Brazier
#30Ingot

SparkScrollbar

#1Inferno
#2Ember
#3Bellows
#4Crucible
#5Hearth
#6Pyre
#7Cinder
#8Spark
#9Tinder
#10Anvil
#11Forge
#12Smelter
#13Bloom
#14Slag
#15Quench
#16Temper
#17Rivet
#18Hammer
#19Mortar
#20Kiln
#21Foundry
#22Ironworks
#23Bellower
#24Striker
#25Quencher
#26Gilder
#27Smith
#28Wrought
#29Brazier
#30Ingot

<template>
   <SparkDemoBox :source="source">
      <div class="grid grid-cols-1 min-[480px]:grid-cols-2 gap-4">
         <!-- Default browser scrollbar (no .spark-scrollbar class) -->
         <div class="spark-demo-scrollbar-pane flex flex-col gap-2 min-w-0">
            <p class="m-0 text-[0.6875rem] font-semibold uppercase tracking-[0.08em] text-white/40">Default browser scrollbar</p>

            <div class="spark-demo-scrollbar-list max-h-60 overflow-y-auto rounded-kf-md border border-white/[0.08] bg-white/[0.02]">
               <ul>
                  <li v-for="entry in entries" :key="entry.id">
                     <span class="flex-shrink-0 tabular-nums text-[0.6875rem] font-semibold text-white/[0.35] w-7">#{{ entry.id }}</span>
                     <span class="font-medium">{{ entry.label }}</span>
                  </li>
               </ul>
            </div>
         </div>

         <!-- SparkScrollbar — wraps the same content -->
         <div class="spark-demo-scrollbar-pane flex flex-col gap-2 min-w-0">
            <p class="m-0 text-[0.6875rem] font-semibold uppercase tracking-[0.08em] text-white/40">SparkScrollbar</p>

            <SparkScrollbar :max-height="240" tag="div" class="spark-demo-scrollbar-list max-h-60 overflow-y-auto rounded-kf-md border border-white/[0.08] bg-white/[0.02]">
               <ul>
                  <li v-for="entry in entries" :key="entry.id">
                     <span class="flex-shrink-0 tabular-nums text-[0.6875rem] font-semibold text-white/[0.35] w-7">#{{ entry.id }}</span>
                     <span class="font-medium">{{ entry.label }}</span>
                  </li>
               </ul>
            </SparkScrollbar>
         </div>
      </div>
   </SparkDemoBox>
</template>

<script setup>
import { SparkScrollbar } from '@katforge/spark';
import source from './SparkDemoScrollbar.vue?raw';

const fragments = [
   'Inferno',  'Ember',    'Bellows',   'Crucible',
   'Hearth',   'Pyre',     'Cinder',    'Spark',
   'Tinder',   'Anvil',    'Forge',     'Smelter',
   'Bloom',    'Slag',     'Quench',    'Temper',
   'Rivet',    'Hammer',   'Mortar',    'Kiln',
   'Foundry',  'Ironworks','Bellower',  'Striker',
   'Quencher', 'Gilder',   'Smith',     'Wrought',
   'Brazier',  'Ingot',
];

const entries = fragments.map ((label, i) => ({ id: i + 1, label }));
</script>

<style scoped>
/* Reset the browser scrollbar styles for the LEFT pane only. The right
   pane is wrapped in <SparkScrollbar> which applies the .spark-scrollbar
   class itself. */
.spark-demo-scrollbar-pane:first-child .spark-demo-scrollbar-list {
   scrollbar-width: auto;
   scrollbar-color: auto;
}

.spark-demo-scrollbar-pane:first-child .spark-demo-scrollbar-list::-webkit-scrollbar         { width: 16px; }
.spark-demo-scrollbar-pane:first-child .spark-demo-scrollbar-list::-webkit-scrollbar-track   { background: initial; }
.spark-demo-scrollbar-pane:first-child .spark-demo-scrollbar-list::-webkit-scrollbar-thumb   { background: initial; }

.spark-demo-scrollbar-list ul {
   list-style: none;
   margin: 0;
   padding: 0.375rem;
   display: flex;
   flex-direction: column;
   gap: 0.125rem;
}

.spark-demo-scrollbar-list li {
   display: flex;
   align-items: center;
   gap: 0.625rem;
   padding: 0.5rem 0.625rem;
   border-radius: 0.375rem;
   font-size: 0.8125rem;
   color: rgba(255, 255, 255, 0.85);
   background: rgba(255, 255, 255, 0.02);
   transition: background 100ms ease;
}

.spark-demo-scrollbar-list li:hover {
   background: rgba(255, 255, 255, 0.06);
}
</style>

Vue

<template>
   <SparkScrollbar :max-height="320">
      <ul>
         <li v-for="entry in entries" :key="entry.id">{{ entry.label }}</li>
      </ul>
   </SparkScrollbar>
</template>

The styling lives as a public utility class in katforge.css, so existing scrolling elements can adopt the look without an extra wrapper:

Vue

<ul class="my-list spark-scrollbar" style="overflow-y: auto; max-height: 20rem;">…</ul>

Props

Prop	Type	Default	Description
`maxHeight`	`number \| string`	—	Cap on the scroll container's height. Numbers are pixels; strings pass through (e.g. `'50vh'`, `'24rem'`).
`maxWidth`	`number \| string`	—	Cap on width.
`axis`	`'y' \| 'x' \| 'both'`	`'y'`	Which axis scrolls. The other is `overflow: hidden`.
`tag`	`string`	`'div'`	HTML tag for the wrapper.

Cross-browser

Firefox: uses scrollbar-width: thin + scrollbar-color. Always rendered.
Chromium / WebKit: ::-webkit-scrollbar rules, 8 px wide, transparent track, thumb starts at 14% white and brightens to brand primary at 55% on hover.
Both: the bar respects the container's border-radius, so rounded panels don't get a square scrollbar bleeding past the corner.