Card
Card
The Card category provides building blocks for analytics dashboards. There is a base <XACard> container plus specialised variants for metrics, progress tracking, quotas, and chart visualisations.
Components
<XACard />
Base card container with an optional header (title, description, icon), collapsible body, footer slot, and border variants for status states.
<XACard
title="Recent Activity"
description="Last 30 days"
icon="i-lucide-activity"
collapsible
variant="default"
>
<p>Card body content</p>
<template #header-actions>
<UButton size="xs" label="View all" />
</template>
<template #footer>
<span class="text-sm text-neutral-500">Updated just now</span>
</template>
</XACard>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | '' | Card header title. |
description | string | '' | Subtitle below the title. |
icon | string | '' | Lucide icon name shown in the header. |
collapsible | boolean | false | Show a collapse toggle button. |
collapsed | boolean | false | Initial collapsed state. |
padding | boolean | true | Apply default body padding. |
divider | boolean | true | Show divider line under the header. |
variant | 'default' | 'error' | 'warning' | 'success' | 'default' | Border color variant. |
Slots
default, header-actions, footer
<XACardStat />
Single-metric stat card with automatic number formatting, trend badge, and configurable icon.
<XACardStat
label="Monthly Revenue"
:value="48500"
:trend="12.4"
trend-label="vs last month"
icon="i-lucide-dollar-sign"
icon-color="success"
format="currency"
currency-symbol="$"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Required. Metric label. |
value | string | number | — | Required. Metric value. |
trend | number | null | undefined | Percentage change (positive = up, negative = down). |
trendLabel | string | '' | Descriptive label beside the trend badge. |
description | string | '' | Secondary text below the value. |
icon | string | '' | Lucide icon name. |
iconColor | 'primary' | 'success' | 'warning' | 'error' | 'neutral' | 'primary' | Icon background/color theme. |
size | 'sm' | 'md' | 'lg' | 'md' | Value font size. |
format | 'number' | 'currency' | 'percent' | 'none' | 'none' | Number formatting mode. |
currencySymbol | string | '$' | Symbol prepended in currency format. |
<XAStatsCard />
Option-object-based stats card with full Intl number formatting and color theming.
<XAStatsCard
title="Total Users"
:value="12400"
format="number"
icon="i-lucide-users"
color="primary"
:trend="5.2"
trend-label="from last month"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Required. Card label. |
value | number | string | undefined | Metric value. |
format | 'number' | 'currency' | 'percent' | 'number' | Number formatting mode. |
currency | string | 'USD' | ISO currency code for currency format. |
locale | string | 'en-US' | Locale for Intl formatting. |
icon | string | '' | Lucide icon name. |
color | string | 'primary' | Icon/accent color theme. |
trend | number | undefined | Percentage change. |
trendLabel | string | '' | Label beside the trend indicator. |
description | string | '' | Secondary description text. |
loading | boolean | false | Show loading skeleton. |
<XAStatsGrid />
Responsive grid that renders an array of stat objects as <XAStatsCard> components.
<XAStatsGrid
:stats="[
{ title: 'Revenue', value: 48500, format: 'currency', icon: 'i-lucide-dollar-sign', trend: 12.4 },
{ title: 'Users', value: 3200, format: 'number', icon: 'i-lucide-users', trend: -2.1 },
]"
:columns="2"
gap="md"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
stats | array | [] | Array of stat objects (see XAStatsCard props). |
columns | 1 | 2 | 3 | 4 | 5 | 6 | 4 | Number of columns at the widest breakpoint. |
gap | 'sm' | 'md' | 'lg' | 'md' | Grid gap size. |
locale | string | 'en-US' | Locale passed to each child card. |
<XACardKpi />
Slot-based KPI card. All content is provided through named slots: label, value, trend, and chart.
<XACardKpi>
<template #label>Monthly Recurring Revenue</template>
<template #value>$84,200</template>
<template #trend>
<span class="text-success-500">+8.3%</span>
</template>
<template #chart>
<XAChartLine :data="data" :categories="categories" :height="60" />
</template>
</XACardKpi>
This component has no props — it is entirely slot-driven.
<XACardKpiSimple />
Compact KPI card with automatic currency formatting, an optional trend indicator, and a budget progress bar.
<XACardKpiSimple
label="Actual Spend"
:value="63000"
:trend="-4"
:budget="80000"
show-percentage
color="#10b981"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Required. KPI label. |
value | string | number | — | Required. KPI value (numbers are formatted as currency). |
trend | number | null | undefined | Percentage change. |
color | string | '#3b82f6' | Dot accent color. |
showPercentage | boolean | false | Show a progress bar as % of budget. |
budget | number | 0 | Budget cap used to calculate the progress bar. |
<XACardProgress />
Progress card that can render a horizontal progress bar, a donut circle, or both.
<XACardProgress
label="Storage Used"
:value="73"
:max="100"
subtitle="27 GB remaining"
type="both"
color="warning"
size="md"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Required. Metric label. |
value | number | — | Required. Current value. |
max | number | 100 | Maximum value. |
subtitle | string | '' | Text shown beside the percentage. |
type | 'bar' | 'circle' | 'both' | 'bar' | Which visualization to render. |
color | 'primary' | 'success' | 'warning' | 'error' | string | 'primary' | Progress fill color. |
size | 'sm' | 'md' | 'lg' | 'md' | Label/circle size variant. |
<XACardProgressCircle />
Compact card pairing a XAChartProgressCircle with a text label and formatted value.
<XACardProgressCircle
label="Task Completion"
value="48 / 60"
:progress="80"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Required. Card label. |
value | number | string | — | Required. Displayed value text. |
progress | number | — | Required. Circle fill percentage (0–100). |
color | string | undefined | Custom circle color. |
<XACardQuota />
Displays multiple usage quotas in a grid or list layout with warning/critical/exceeded badges and optional overage pricing.
<XACardQuota
title="Plan Usage"
:quotas="[
{ label: 'API Calls', used: 8200, limit: 10000, unit: 'calls', icon: 'i-lucide-zap', warningThreshold: 80 },
{ label: 'Storage', used: 4.2, limit: 5, unit: 'GB', icon: 'i-lucide-hard-drive' },
]"
reset-date="2026-04-01"
show-summary
current-plan="Pro"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
quotas | array | — | Required. Array of quota objects. |
title | string | '' | Card title. |
description | string | '' | Card subtitle. |
resetDate | Date | string | null | null | Quota reset date shown in the header. |
layout | 'grid' | 'list' | 'grid' | Layout mode. |
columns | number | — | Number of grid columns. |
showSummary | boolean | false | Show a footer summarising limits reached. |
currentPlan | string | '' | Plan name shown in the summary footer. |
Emits
| Event | Payload | Description |
|---|---|---|
upgrade | — | Fired when the "Upgrade Plan" button is clicked. |
<XACardQuotaBar />
Single-resource quota card with a UProgress bar, optional auto-color thresholds, and a footer slot.
<XACardQuotaBar
title="API Requests"
subtitle="This billing period"
:value="7800"
:max="10000"
unit="calls"
color="primary"
auto-color
show-percent
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Required. Card title. |
value | number | — | Required. Current usage value. |
max | number | — | Required. Maximum limit. |
subtitle | string | '' | Optional subtitle. |
unit | string | '' | Unit label (e.g. 'GB'). |
color | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'neutral' | 'primary' | Progress bar color. |
icon | string | '' | Lucide icon name. |
showPercent | boolean | false | Show percentage instead of value/max. |
decimals | number | 0 | Decimal places for formatted values. |
autoColor | boolean | false | Auto-switch to warning/error color at thresholds. |
warningThreshold | number | 80 | Percentage at which to switch to warning color. |
errorThreshold | number | 95 | Percentage at which to switch to error color. |
<XACardRevenue />
Revenue metric card with an embedded area sparkline, name, value, and optional comparison row.
<XACardRevenue
name="Net Revenue"
value="$124,800"
:data="revenueData"
:categories="{ revenue: { name: 'Revenue', color: '#3b82f6' } }"
comparison-label="vs last month"
comparison-value="+12%"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | — | Required. Metric name. |
value | string | number | — | Required. Formatted metric value. |
data | ChartDataItem[] | — | Required. Time-series data array ({ date, ...values }). |
categories | Record<string, { name: string; color: string }> | — | Required. Chart category definitions. |
comparisonLabel | string | '' | Label for the comparison row. |
comparisonValue | string | number | '' | Value for the comparison row. |
height | number | 90 | Chart height in px. |
xNumTicks | number | 4 | Number of X-axis ticks. |
yNumTicks | number | 1 | Number of Y-axis ticks. |
curveType | 'linear' | 'natural' | 'monotone' | 'step' | 'linear' | Chart curve type. |
hideLegend | boolean | true | Hide the chart legend. |
<XACardRevenueBar />
Revenue card with an embedded grouped bar chart.
<XACardRevenueBar
name="Sales by Channel"
value="$84,200"
:data="salesData"
:categories="{
online: { name: 'Online', color: '#3b82f6' },
retail: { name: 'Retail', color: '#10b981' },
}"
:height="328"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | — | Required. Chart card name. |
value | string | number | — | Required. Summary value. |
data | ChartDataItem[] | — | Required. Chart data array. |
categories | Record<string, { name: string; color: string }> | — | Required. Bar categories. |
comparisonLabel | string | '' | Comparison row label. |
comparisonValue | string | number | '' | Comparison row value. |
height | number | 328 | Chart height in px. |
xNumTicks | number | 6 | X-axis ticks. |
yNumTicks | number | 5 | Y-axis ticks. |
groupPadding | number | 0 | Padding between bar groups. |
barPadding | number | 0.2 | Padding between bars within a group. |
radius | number | 4 | Bar corner radius. |
hideLegend | boolean | false | Hide the chart legend. |
yGridLine | boolean | false | Show horizontal grid lines. |
<XACardIndicator />
Minimal indicator card: uppercase label, large value, and an up/down trend percentage versus the previous month.
<XACardIndicator
label="Conversion Rate"
value="3.48%"
:trend="2.1"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Required. Metric label. |
value | number | string | — | Required. Metric value. |
trend | number | — | Required. Month-over-month percentage change. |
<XACardSparkline />
Stat card with a small inline sparkline (area or line chart) rendered from a flat number array.
<XACardSparkline
label="Weekly Signups"
value="1,240"
:data="[120, 145, 98, 160, 175, 140, 190]"
:trend="8.5"
chart-type="area"
format="number"
color="#6366f1"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Required. Metric label. |
value | string | number | — | Required. Metric value. |
data | number[] | — | Required. Flat array of numeric values for the sparkline. |
trend | number | null | undefined | Percentage trend badge value. |
chartType | 'line' | 'area' | 'area' | Sparkline chart type. |
color | string | '#06b6d4' | Chart line/area color. |
format | 'number' | 'currency' | 'percent' | 'none' | 'none' | Value formatting mode. |
currencySymbol | string | '$' | Symbol for currency format. |
<XACardDonut />
Donut chart card with a legend table showing name and percentage share for each segment.
<XACardDonut
title="Revenue by Region"
total-value="$248,000"
:data="[
{ name: 'North America', value: 45, color: '#3b82f6' },
{ name: 'Europe', value: 30, color: '#10b981' },
{ name: 'Asia Pacific', value: 25, color: '#f59e0b' },
]"
center-label="Total"
center-sub-label="$248K"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Required. Card title. |
totalValue | string | — | Required. Formatted total displayed under the title. |
data | { name: string; value: number; color: string }[] | — | Required. Donut segments. |
centerLabel | string | undefined | Text on the first line of the donut center. |
centerSubLabel | string | undefined | Text on the second line of the donut center. |
legendNameLabel | string | 'Category' | Header for the name column in the legend table. |
legendValueLabel | string | 'Share' | Header for the value column in the legend table. |
<XACardChart />
Generic area-chart card with a subtitle, comparison row, and optional legend.
<XACardChart
name="Page Views"
:value="84200"
:chart-data="pageViewData"
:categories="{ views: { name: 'Views', color: '#6366f1' } }"
comparison-label="vs last month"
comparison-value="+9.4%"
:show-legend="false"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | — | Required. Card name/subtitle. |
value | string | number | — | Required. Summary metric value. |
chartData | ChartDataItem[] | — | Required. Area chart data ({ date, ...values }). |
categories | Record<string, { name: string; color: string }> | — | Required. Chart categories. |
height | number | 90 | Chart height in px. |
showLegend | boolean | false | Show the chart legend. |
curveType | any | CurveType.Linear | Curve interpolation type. |
<XACardChartBlock />
Card variant that wraps a chart slot and overlays a title and description at the bottom. Useful as a decorative/feature card.
<XACardChartBlock
title="Growth Trajectory"
text="Steady month-over-month growth across all channels."
>
<XAChartLine :data="data" :categories="categories" :height="160" />
</XACardChartBlock>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Required. Overlay title. |
text | string | — | Required. Overlay description text. |
<XACardChartRevenue />
Revenue card containing a grouped bar chart with configurable axes and legend.
<XACardChartRevenue
title="Monthly Revenue"
value="$1.2M YTD"
:data="revenueData"
:categories="{
desktop: { name: 'Desktop', color: '#3b82f6' },
mobile: { name: 'Mobile', color: '#10b981' },
}"
:height="200"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | '' | Card title. |
value | string | '' | Summary value shown under the title. |
data | RevenueDataItem[] | — | Required. Bar chart data ({ month, desktop, mobile, ... }). |
categories | RevenueCategories | — | Required. Category name/color map. |
height | number | 200 | Chart height in px. |
yAxis | string[] | ['desktop', 'mobile'] | Data keys for the Y axis. |
groupPadding | number | 0 | Padding between bar groups. |
barPadding | number | 0.2 | Padding between bars. |
radius | number | 4 | Bar corner radius. |
yNumTicks | number | 4 | Y-axis tick count. |
legendPosition | 'top' | 'bottom' | 'left' | 'right' | 'top' | Legend placement. |
hideLegend | boolean | true | Hide the legend. |
yGridLine | boolean | true | Show horizontal grid lines. |
<XACardChartRevenueLine />
Revenue card with a line chart — designed for current-year vs last-year comparisons.
<XACardChartRevenueLine
title="Revenue Trend"
value="$84,200"
:data="trendData"
:categories="{
current: { name: 'This Year', color: '#3b82f6' },
last_year: { name: 'Last Year', color: '#d1d5db' },
}"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | '' | Card title. |
value | string | '' | Summary value. |
data | RevenueLineDataItem[] | — | Required. Line data ({ date, current, last_year }). |
categories | RevenueLineCategories | — | Required. Category map. |
height | number | 180 | Chart height in px. |
xNumTicks | number | 4 | X-axis ticks. |
yNumTicks | number | 3.5 | Y-axis ticks. |
curveType | 'linear' | 'natural' | 'monotone' | 'step' | 'linear' | Curve interpolation. |
legendPosition | 'top' | 'bottom' | 'left' | 'right' | 'top' | Legend placement. |
hideLegend | boolean | true | Hide the legend. |
hideXAxis | boolean | true | Hide X-axis labels. |
yGridLine | boolean | true | Show horizontal grid lines. |
<XACardChartExpenses />
Expenses card with a stacked or grouped bar chart and full axis control.
<XACardChartExpenses
title="Expenses by Product"
value="$32,400"
:data="expensesData"
:categories="{
sales: { name: 'Sales', color: '#3b82f6' },
counter: { name: 'Counter', color: '#f59e0b' },
}"
stacked
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | '' | Card title. |
value | string | '' | Summary value. |
data | ExpensesDataItem[] | — | Required. Bar data ({ product, sales, counter }). |
categories | ExpensesCategories | — | Required. Category map. |
height | number | 140 | Chart height in px. |
stacked | boolean | true | Stack bars. |
hideXAxis | boolean | true | Hide X-axis labels. |
yNumTicks | number | 4 | Y-axis ticks. |
yAxis | string[] | ['sales', 'counter'] | Data keys. |
legendPosition | 'top' | 'bottom' | 'left' | 'right' | 'top' | Legend placement. |
hideLegend | boolean | false | Hide the legend. |
radius | number | 8 | Bar corner radius. |
barPadding | number | 0.6 | Bar padding. |
<XACardChartFinance />
Finance breakdown card combining a donut chart with a percentage-based legend.
<XACardChartFinance
:categories="[
{ name: 'Marketing', value: 42000, color: '#3b82f6' },
{ name: 'Engineering', value: 68000, color: '#10b981' },
{ name: 'Operations', value: 24000, color: '#f59e0b' },
]"
center-label="Total Spend"
currency="USD"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
categories | FinanceCategory[] | — | Required. Segments: { color, name, value }. |
centerLabel | string | 'Total Spent' | Donut center label. |
currency | string | 'USD' | Currency for the formatted total. |
locale | string | 'en-US' | Locale for Intl formatting. |
height | number | 200 | Donut chart height in px. |
arcWidth | number | 10 | Donut arc stroke width. |
padAngle | number | 0.1 | Padding between segments. |
radius | number | 4 | Segment corner radius. |
<XACardChartWinLoss />
Win/loss chart card using a line chart segmented by day.
<XACardChartWinLoss
title="Daily Win/Loss"
:data="winLossData"
:categories="{
wins: { name: 'Wins', color: '#10b981' },
losses: { name: 'Losses', color: '#ef4444' },
}"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | '' | Card title. |
data | WinLossDataItem[] | — | Required. Data array ({ day, ...values }). |
categories | WinLossCategories | — | Required. Category map. |
yAxis | string[] | [] | Data keys for Y axis. |
height | number | 160 | Chart height in px. |
stacked | boolean | false | Stack the series. |
radius | number | 3 | Bar corner radius. |
groupPadding | number | 0.2 | Group padding. |
barPadding | number | 0.2 | Bar padding. |
hideLegend | boolean | true | Hide the legend. |
yNumTicks | number | 4 | Y-axis ticks. |
<XACardStatsSummary />
Summary card combining an area chart with a prominent metric value and a comparison note.
<XACardStatsSummary
title="Total Revenue"
:value="124800"
:chart-data="summaryData"
:categories="{ revenue: { name: 'Revenue', color: '#3b82f6' } }"
comparison-label="vs Last Months"
comparison-value="+14.2%"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | — | Required. Card title/label. |
value | string | number | — | Required. Featured metric value. |
chartData | ChartDataItem[] | — | Required. Area chart data ({ date, ...values }). |
categories | Record<string, { name: string; color: string }> | — | Required. Chart categories. |
height | number | 90 | Chart height in px. |
showLegend | boolean | false | Show the chart legend. |
curveType | any | CurveType.Linear | Curve interpolation. |
comparisonLabel | string | 'vs Last Months' | Comparison label text. |
comparisonValue | string | undefined | Comparison value (shown in success color). |
<XACardActiveUsers />
Displays an active-user count with a stacked avatar list, trend indicator, and overflow badge.
<XACardActiveUsers
label="Active Members"
count="1,234"
:users="[
{ name: 'Alice Johnson', avatar: '/avatars/alice.png' },
{ name: 'Bob Smith' },
{ name: 'Carol White', avatar: '/avatars/carol.png' },
]"
:trend="12.5"
trend-label="from last month"
:max-display="4"
subtitle="currently online"
/>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label | string | — | Required. Card label. |
count | string | number | — | Required. Active user count (can be pre-formatted like '12.4k'). |
users | { name: string; avatar?: string }[] | [] | Users to show in the avatar stack. |
trend | number | undefined | Percentage trend (positive or negative). |
trendLabel | string | 'from previous month' | Text label beside the trend. |
maxDisplay | number | 4 | Max avatars before showing +X more. |
subtitle | string | '' | Text shown beside the avatar stack. |
AI Context
category: Card
package: "@xenterprises/nuxt-x-app"
components:
- XACard
- XACardStat
- XAStatsCard
- XAStatsGrid
- XACardKpi
- XACardKpiSimple
- XACardProgress
- XACardProgressCircle
- XACardQuota
- XACardQuotaBar
- XACardRevenue
- XACardRevenueBar
- XACardIndicator
- XACardSparkline
- XACardDonut
- XACardChart
- XACardChartBlock
- XACardChartRevenue
- XACardChartRevenueLine
- XACardChartExpenses
- XACardChartFinance
- XACardChartWinLoss
- XACardStatsSummary
- XACardActiveUsers
use-when: >
Building dashboard overview pages, KPI panels, analytics summaries,
or resource usage sections. Use XACard as a general purpose container,
XAStatsGrid for a row of metrics, and the specialised chart cards
(Revenue, Sparkline, Donut, etc.) for inline data visualisation.
patterns:
- XAStatsGrid accepts a flat stats array; individual cards accept discrete props.
- Chart cards require a `data` array and a `categories` map keyed by data field.
- XACardQuota manages multiple resources in one card; XACardQuotaBar handles one.
- Trend props accept positive (up) and negative (down) numbers — colors are automatic.
