GkCard

A card primitive for admin layouts: a bordered, rounded surface (optional top media) with optional title / subtitle / text convenience props, slots for full composition, and GkCardActions for a footer action row. The API and layout are inspired by Vuetify’s VCard; the implementation is God Kit–native (Vue SFCs, var(--gk-*) tokens, no Vuetify runtime).

When to use

• Dashboard tiles, feed items, and lists of entities (with GkDataTable or custom grids) where you need a consistent surface.
• Teasers with an image, headline, and CTA row (GkButton inside GkCardActions).
• Navigable tiles as a link (href) or a clickable div with role="button" when you need a single surface action without nested links.

For modal workflows, use GkDialog. For a flex region without a full card chrome, use GkStack or GkContainer.

Live Examples

Basic elevated card

Use the default slot for simple content.

Default elevated surface with design-token border and shadow.

vue

<script setup lang="ts">
import { GkCard } from 'god-kit/vue'
</script>

<template>
  <GkCard :max-width="400">
    Default elevated surface with design-token border and shadow.
  </GkCard>
</template>

Best practice: Start with the default elevated variant for dashboard cards, then change variant only when the surface hierarchy requires it.

Convenience title, subtitle, and text

Use props for the common header/body layout.

Invoice #1042

Acme Corp - due in 3 days

The amount is ready for review.

Extra paragraph in the default slot.

vue

<script setup lang="ts">
import { GkCard } from 'god-kit/vue'
</script>

<template>
  <GkCard
    :max-width="400"
    title="Invoice #1042"
    subtitle="Acme Corp - due in 3 days"
    text="The amount is ready for review."
  >
    Extra paragraph in the default slot.
  </GkCard>
</template>

Best practice: Use title/subtitle/text props for simple cards; switch to slots when the header needs custom markup.

Media and actions

Add top media and a footer action row.

Landscape

Picsum sample media

Top media uses object-fit: cover and a token min-height.

vue

<script setup lang="ts">
import { GkButton, GkCard, GkCardActions, GkCardText } from 'god-kit/vue'
</script>

<template>
  <GkCard
    :max-width="400"
    image="https://picsum.photos/seed/gkkit-card/800/400"
    title="Landscape"
    subtitle="Picsum sample media"
  >
    <GkCardText>
      Top media uses object-fit: cover and a token min-height.
    </GkCardText>

    <template #actions>
      <GkCardActions>
        <GkButton type="button" variant="secondary" size="sm" slim>
          Later
        </GkButton>
        <GkButton type="button" size="sm" slim>
          Open
        </GkButton>
      </GkCardActions>
    </template>
  </GkCard>
</template>

Best practice: Wrap action buttons in GkCardActions so spacing and alignment stay consistent across cards.

Header slots

Use slots for custom prepend, title, subtitle, and append regions.

Custom title slot

With a color chip in prepend

New

Use #prepend and #append for icons, avatars, or status chips.

vue

<script setup lang="ts">
import { GkCard } from 'god-kit/vue'
</script>

<template>
  <GkCard :max-width="400">
    <template #prepend>
      <span class="status-dot" aria-hidden="true" />
    </template>

    <template #title>
      Custom title slot
    </template>

    <template #subtitle>
      With a color chip in prepend
    </template>

    <template #append>
      <span class="badge">New</span>
    </template>

    Use #prepend and #append for icons, avatars, or status chips.
  </GkCard>
</template>

<style scoped>
.status-dot {
  width: 0.5rem;
  height: 0.5rem;
  border-radius: 50%;
  background: var(--gk-color-primary);
  margin-top: 0.35rem;
}

.badge {
  display: inline-block;
  padding: 0.125rem 0.5rem;
  font-size: var(--gk-text-body-xs-size);
  font-weight: 600;
  line-height: var(--gk-text-body-xs-line-height);
  color: var(--gk-color-text-on-primary);
  background: var(--gk-color-primary);
  border-radius: var(--gk-radius-sm);
}
</style>

Best practice: Use #prepend and #append for visual metadata such as icons, avatars, status dots, or lightweight badges.

Link card

Use href for navigation so the root is a real anchor.

As a link

Root is an anchor; opens in a new tab.

vue

<script setup lang="ts">
import { GkCard } from 'god-kit/vue'
</script>

<template>
  <GkCard
    href="https://example.com"
    target="_blank"
    rel="noopener noreferrer"
    variant="outlined"
    hover
    :max-width="320"
    title="As a link"
    text="Root is an anchor; opens in a new tab."
  />
</template>

Best practice: Do not place buttons or other nested interactive controls inside a linked card.

Clickable surface

Use clickable when the whole card is a single non-navigation action.

Clickable surface

Role is button; clicks: 0

vue

<script setup lang="ts">
import { ref } from 'vue'
import { GkCard } from 'god-kit/vue'

const count = ref(0)
</script>

<template>
  <GkCard
    clickable
    variant="plain"
    :max-width="320"
    title="Clickable surface"
    :text="`Role is button; clicks: ${count}`"
    @click="count++"
  />
</template>

Best practice: Prefer href for navigation; use clickable for in-page actions and keep nested controls out of the card.

Loading, disabled, and variants

Combine state props with visual variants.

Loading compact card

The toggle is outside the card to avoid nested interactive controls.

Disabled + tonal

Tonal background with no lift.

vue

<script setup lang="ts">
import { ref } from 'vue'
import { GkButton, GkCard } from 'god-kit/vue'

const loading = ref(false)
</script>

<template>
  <div class="states-example">
    <div class="states-example__stack">
      <GkButton type="button" variant="secondary" @click="loading = !loading">
        Toggle loading
      </GkButton>

      <GkCard
        variant="outlined"
        density="compact"
        :loading="loading"
        :rounded="false"
        :max-width="320"
        title="Loading compact card"
        text="The toggle is outside the card to avoid nested interactive controls."
      />
    </div>

    <GkCard
      variant="tonal"
      flat
      disabled
      :max-width="320"
      title="Disabled + tonal"
      text="Tonal background with no lift."
    />
  </div>
</template>

<style scoped>
.states-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--gk-space-4);
  align-items: flex-start;
}

.states-example__stack {
  display: flex;
  flex-direction: column;
  gap: var(--gk-space-2);
  align-items: flex-start;
}
</style>

Best practice: Keep loading toggles outside the card when the card itself is busy; disabled cards are not interactive.

API

GkCard — props

Prop	Type	Default	Description
variant	'elevated' | 'outlined' | 'tonal' | 'plain'	'elevated'	elevated: surface + token shadow. outlined: border, no default shadow. tonal: primary-tinted fill. plain: no border, transparent.
flat	boolean	false	Forces no shadow (still applies border for non-plain variants).
hover	boolean	false	Stronger shadow on hover (ignored if disabled or flat).
disabled	boolean	false	Disables pointer events and lowers opacity; root is not a link while disabled.
loading	boolean	false	Full-card overlay and aria-busy.
image	string	—	Top media URL; overridden by slot #image.
title	string | number	—	Shorthand for a header line (overridden by #title).
subtitle	string | number	—	Shorthand (overridden by #subtitle).
text	string | number	—	Body copy block (overridden by #text).
href	string	—	Renders the root as <a> (unless disabled).
rel	string	—	For anchors; if target="_blank", defaults to noopener noreferrer.
target	string	—	Anchor target.
download	boolean | string	—	Passed to the anchor when href is set.
prependAvatar	string	—	Optional header avatar URL (see #prepend).
appendAvatar	string	—	Optional trailing avatar URL (see #append).
clickable	boolean	false	If there is no href, the root is focusable with role="button" and keyboard Enter / Space (set only when the whole card is the control).
width / maxWidth / height / maxHeight	string | number	—	Size on the root (numbers are treated as px).
as	'div' | 'article' | 'section'	'div'	Root element when the card is not a link.
density	'comfortable' | 'compact'	'comfortable'	Slightly tighter padding.
rounded	boolean	true	When false, corner radius is 0.

Additional attributes (for example aria-label, id, class) are forwarded to the root element, except class / style are merged with the component’s own.

GkCard — events

Event	Payload	Description
click	MouseEvent | KeyboardEvent	For anchors, clickable cards, and any pointer/keyboard activation on the root.

GkCard — slots

Slot	Description
default	Main content after the optional text block.
image	Top media; replaces image.
title / subtitle / text	Override the matching props.
item	Extra block inside the header row (below title/subtitle) when a header is shown.
prepend / append	Header start/end regions (or use avatar props).
actions	Footer; wrap actions in GkCardActions for layout.
loader	Replaces the default GkSpinner in the loading overlay.

Subcomponents

Component	Role
GkCardItem	Single header row: prepend, title stack, default + #item slot, append.
GkCardTitle / GkCardSubtitle / GkCardText	Typography blocks for custom layouts; GkCard uses them internally for convenience content. GkCardSubtitle / GkCardText support an opacity prop (CSS custom property on the node).
GkCardActions	End-aligned, wrapping row for GkButton (or other controls).

Tokens

Token	Purpose
--gk-card-radius	Corner radius.
--gk-card-shadow / --gk-card-shadow-hover	Elevation.
--gk-card-border-width	Border.
--gk-card-padding / --gk-card-padding-compact	Inner padding.
--gk-card-media-min-height	Min height of top media.
--gk-card-actions-min-height / --gk-card-actions-gap	Action row.
--gk-card-loader-overlay	Scrim over the card when loading.

Try It

Use the playground to change common options, preview the result, and copy generated Vue code.

VariantelevatedoutlinedtonalplainDensitycomfortablecompactTitleSubtitleTextUse this playground to learn the core props without a full SFC compiler.Image URLHref

flat hover loading disabled rounded clickable

Editable GkCard

Generated code updates as you edit

Use this playground to learn the core props without a full SFC compiler.

vue

<script setup lang="ts">
import { GkCard } from 'god-kit/vue'
</script>

<template>
  <GkCard
    title="Editable GkCard"
    subtitle="Generated code updates as you edit"
    text="Use this playground to learn the core props without a full SFC compiler."
    hover
    :max-width="360"
  />
</template>

Edge case (link, don’t nest buttons in a link)

If the root is an <a> (href), do not place GkButton or other focusable elements that perform a second navigation inside the same card (use a clickable card with @click and route in script, or keep only text in the link card).

Accessibility

• Loading sets aria-busy="true" on the root.
• Clickable cards without href use role="button" and tabindex="0"; Enter and Space emit click. Prefer a real <a href> (or your router link as the root) for navigation so users get standard link behavior.
• When the whole card is a single action, do not add separate primary buttons inside the same card unless you use a different pattern (e.g. the card is static and only the buttons act).

Related components

• GkButton — primary actions inside GkCardActions
• GkStack — spacing and alignment around cards
• GkDataTable — mobile layout uses a stacked “card” pattern