Docs/Overlay Components

Overlay Components

Surfaces that float over the page: modals, tooltips, flash toasts, and the login / account menu.

SparkModal

Animated modal with backdrop blur, card slide-up, escape-to-close, focus trapping, and outside-click dismiss. Supports ARIA attributes for screen readers.

Vue
<template>
   <button @click="open = true">Open Modal</button>

   <SparkModal v-model="open" title="Confirm">
      <p>Are you sure?</p>

      <div class="flex gap-3 justify-end mt-4">
         <button class="kf-btn-ghost" @click="open = false">Cancel</button>
         <button class="kf-btn" @click="open = false">Confirm</button>
      </div>
   </SparkModal>
</template>

Props

PropTypeDefaultDescription
modelValuebooleanControls visibility via v-model
titlestringHeading text (sets aria-labelledby)
labelstringAccessible label when no title
size'sm' | 'md' | 'lg' | 'xl''md'Max width of the card
showClosebooleantrueShow the close button
closeOnOutsidebooleantrueClose on backdrop click
cardClassstring'kf-card'CSS class for the card container
paletteSparkPaletteScopes a palette's CSS variables to this modal. Omit to inherit the host app's palette.

Slots

SlotDescription
defaultModal body content
headerReplaces the default title rendering

SparkTooltip

Hover/focus tooltip that teleports to <body> so it isn't clipped by overflow: hidden ancestors. The trigger renders the default slot. Tooltip content can come from the text prop or the content slot.

Vue
<!-- Plain string tooltip -->
<SparkTooltip text="Used by the leaderboard service to break ties.">
   <span class="info-icon" tabindex="0">?</span>
</SparkTooltip>

<!-- Rich content via slot -->
<SparkTooltip placement="bottom">
   <SparkButton>Hover me</SparkButton>
   <template #content>
      <strong>Pro tip:</strong> press <kbd>?</kbd> for shortcuts.
   </template>
</SparkTooltip>

Props

PropTypeDefaultDescription
textstringTooltip text. Fall back to the content slot if you need markup
placement'top' | 'bottom''top'Preferred side; auto-flips when there's not enough room
openDelaynumber80ms to wait before showing on hover. 0 for instant
disabledbooleanfalseSuppresses the tooltip without unmounting

Slots

SlotDescription
(default)The trigger element. Hovering or focusing it shows the tooltip
contentTooltip body. Overrides text

Form-field integration

SparkInput, SparkSelect, SparkCombobox, and SparkTextarea all read a help prop. When set, a small (?) glyph appears next to the field's label and the help text shows in a SparkTooltip on hover/focus. No setup required:

Vue
<SparkInput
   v-model="username"
   label="Username"
   help="3–20 characters, letters/numbers/dashes only."
   validation="required|alpha_dash"
/>

SparkFlash

Toast notification system. Place SparkFlashContainer once at the app root, then fire messages from anywhere with useFlash ().

Vue
<template>
   <SparkFlashContainer />
   <router-view />
</template>
TypeScript
import { useFlash } from '@katforge/spark';

const flash = useFlash ();

flash.success ('Changes saved');
flash.error ('Something went wrong');
flash.warning ('Rate limit approaching');
flash.info ('Tip: try keyboard shortcuts');

// With options
flash.success ('Saved', { title: 'Settings', duration: 3000 });

// Manual control
const id = flash.success ('Processing...');
flash.dismiss (id);
flash.dismissAll ();

Errors default to 10 seconds; all other types default to 5 seconds. Set duration: 0 for persistent messages that require manual dismissal.

SparkLogin

Drop-in login/register/guest modal. Wired to the @katforge/api's auth module. Handles email/password, OAuth buttons, guest sessions, forgot password, and guest-to-registered upgrade. Composes SparkModal internally.

Live component connected to the KATforge API
Vue
<template>
   <button @click="show = true">Sign In</button>

   <SparkLogin
      v-model="show"
      :providers="[ 'discord', 'google', 'steam' ]"
      @success="onLogin"
   />
</template>

<script setup>
import { ref } from 'vue';

const show = ref (false);

function onLogin (player) {
   show.value = false;
   console.log ('Logged in as', player.name);
}
</script>

Props

PropTypeDefaultDescription
modelValuebooleanControls visibility via v-model
guestbooleantrueShow "Play as Guest" option
providersOAuthProvider[][]OAuth buttons to display
managestring'https://katforge.com'Account management base URL
callbackUrlstring''OAuth redirect URL

Events

EventPayloadDescription
successPlayerFired after successful authentication. Reached via the Login, Register, Forgot (after reset), or Profile internal views.
errorstringFired with the raw error message.

For most apps, prefer SparkUserMenu — it embeds SparkLogin, the avatar dropdown, and the wallet display behind one component.

SparkUserMenu

The canonical auth surface. Replaces the bespoke "sign in button + login modal + avatar dropdown" pattern that every game used to ship its own copy of. Logged out, it renders a pill-shaped Sign In button that opens an internally-owned SparkLogin. Logged in, it shows the avatar + name + chevron and reveals a dropdown with the user's currency snapshot, four built-in dashboard links (Dashboard, Account Details, My Games, Currency), Sign Out, and any extra items consumers slot in.

Vue
<!-- On katforge.com itself: omit `manage` so links stay same-origin -->
<SparkUserMenu mode="hover" :providers="[ 'discord', 'google' ]" />

<!-- On a game site: pass the dashboard origin so links open katforge.com in a new tab -->
<SparkUserMenu
   mode="hover"
   :providers="[ 'discord', 'google' ]"
   :manage="dashboardUrl"
>
   <template #items="{ close }">
      <NuxtLink to="/leaderboards" @click="close">Leaderboards</NuxtLink>
   </template>
</SparkUserMenu>
PropTypeDefaultDescription
paletteSparkPalettepalettes.stonePalette applied to the embedded login modal.
labelstring'Sign In'Sign In button text.
providersOAuthProvider[][]OAuth providers surfaced in the modal.
guestbooleanfalseForwarded to SparkLogin — show the "Play as Guest" affordance.
managestring''Base URL for dashboard links. Empty → in-site relative links (suitable for katforge.com). A full URL like https://katforge.com renders external links that open in a new tab.
callbackUrlstring''OAuth callback URL passthrough.
mode'click' | 'hover''click'Dropdown trigger. Hover suits desktop nav; click suits mobile.

The Sign In button and the avatar trigger render as the standard KATforge navbar pill — fully rounded, transparent at rest, rgba(255, 255, 255, 0.2) on hover. The dropdown panel uses SparkAvatar, SparkWallet, and built-in icon tiles. The #items slot lands between the four default dashboard links and Sign Out, and receives a close function so consumers can dismiss the menu after navigation.