Stats

A component that displays multiple statistics or feature items in a horizontal row, showing a title and a short description for each. Ideal for highlighting key metrics, features, or value propositions.

Use Cases

• Key statistics or metrics (users, downloads, uptime)
• Feature highlights in hero sections
• Value propositions (Fast, Secure, Reliable)
• Step indicators or process highlights
• Benefits or selling points

Properties

items

Array of stat items displayed horizontally. Type: array. Minimum items: 2. Maximum items: 6. Recommendations: Use 3 items for optimal balance (most common pattern); Use 2‑4 items for statistics or numbers; Use 3‑4 items for feature highlights.

Item structure:

• title (string, required) – Stat title – the prominent text (number, metric, or feature name). Content editable.
• description (string, required) – Stat description – supporting text explaining the title. Content editable.

layout

Layout style for stat items. Type: string. Options: default, minimal, cards, horizontal. Default: default. Visual Impact: default – Stacked layout with large value on top, label below - classic stats display; minimal – Clean, smaller layout with uppercase labels and tight spacing - modern minimal; cards – Individual cards for each stat with hover lift effect - prominent and interactive; horizontal – Label and value side by side - compact row display. Recommendations: landing – Use 'default' for prominent landing page stats with large numbers; dashboard – Use 'cards' for dashboard metrics that may be clickable; footer – Use 'minimal' for stats in footer or compact sections; compact – Use 'horizontal' when space is limited.

style

Visual style for stats container. Type: string. Options: gradient, transparent, bordered, elevated. Default: gradient. Visual Impact: gradient – Themed gradient background (--theme-gradient-start to --theme-gradient-end) - eye-catching, prominent; transparent – No background, primary-colored values - blends with page background; bordered – Outline border only - clean, defined without heavy visual weight; elevated – White background with strong shadow - prominent but neutral colors. Recommendations: landing – Use 'gradient' for eye-catching landing page stats; article – Use 'transparent' when stats are inline with content; section – Use 'bordered' or 'elevated' for distinct stats sections; darkMode – All styles support dark mode automatically.

columns

Number of columns for stats grid on desktop. Type: number. Options: 2, 3, 4. Default: 2. Recommendations: 2items – Use 2 columns for 2 stats; 3items – Use 3 columns for 3 stats; 4items – Use 4 columns for 4 stats (or 2 columns for 2x2 grid).

customCss

Custom CSS styles for advanced styling. Parsed as CSS property-value pairs. Type: string. Examples: "background-color: #f9fafb; padding: 32px; border-radius: 8px;", "gap: 48px; max-width: 1200px;". Security Note: Parsed by cssParser utility. Tenants only affect their own pages (multi-tenant isolation enforced).

Best Practices

• Use Stats when you want to highlight key metrics or features in a horizontal row
• Provide 2‑4 items for balanced horizontal layout (3 is optimal)
• Keep titles short (1‑3 words) – this is the prominent text
• Keep descriptions concise (3‑8 words explaining the benefit)
• Use for high‑level highlights, not detailed explanations

Common Mistakes

Using Stats with 6+ items

Why it's a problem: Too crowded on desktop, poor mobile experience, hard to scan

Fix: Use 2‑4 items (3 is optimal). For more items, use Card components in Grid instead.

Writing long descriptions (10+ words)

Why it's a problem: Stats component designed for quick scannable highlights, not detailed explanations

Fix: Keep descriptions to 3‑8 words. For detailed explanations, use Card components.

Mixing stats and features inconsistently

Why it's a problem: Confusing mix of numbers (‘10K Users’) and concepts (‘Fast’) – lacks visual consistency

Fix: Be consistent: either all numbers/metrics OR all features/concepts, not mixed