ui/packages/ui-analytics

@lilith/ui-analytics

Analytics dashboard components for building data visualization interfaces. Includes metric cards, trend indicators, dashboard layouts, and real-time data displays.

Features

• MetricCard - Display key metrics with trends, sparklines, and variants
• TrendIndicator - Visual trend direction indicators
• DashboardLayout - Responsive grid layout for dashboard widgets
• DashboardWidget - Container component for dashboard items with span control
• DateRangePicker - Date range selection for analytics filtering
• LeaderboardTable - Ranked data display table
• RealtimeMetric - Live updating metric display

Installation

npm install @lilith/ui-analytics
# or
pnpm add @lilith/ui-analytics

Peer Dependencies

npm install react react-dom styled-components

Usage

MetricCard

Display key performance indicators with optional trends and sparklines.

import { MetricCard } from '@lilith/ui-analytics';
import { DollarSign } from 'lucide-react';

<MetricCard
  label="Total Revenue"
  value={125430}
  format="currency"
  change={12.5}
  trend="up"
  sparkline={[100, 120, 115, 140, 135, 150, 145]}
  icon={<DollarSign />}
  variant="success"
  subtext="Last 30 days"
/>

// Clickable metric card
<MetricCard
  label="Active Users"
  value={1234}
  format="number"
  onClick={() => navigate('/users')}
  isActive={activeFilter === 'users'}
/>

DashboardLayout

Create responsive grid layouts for dashboard widgets.

import { DashboardLayout, DashboardWidget } from '@lilith/ui-analytics';
import { MetricCard } from '@lilith/ui-analytics';

<DashboardLayout columns={4} gap={16} minWidgetWidth={280}>
  <DashboardWidget>
    <MetricCard label="Users" value={1234} />
  </DashboardWidget>

  <DashboardWidget>
    <MetricCard label="Revenue" value={56789} format="currency" />
  </DashboardWidget>

  {/* Span multiple columns */}
  <DashboardWidget span={2}>
    <LineChart data={chartData} />
  </DashboardWidget>

  <DashboardWidget span={4}>
    <DataTable data={tableData} />
  </DashboardWidget>
</DashboardLayout>

TrendIndicator

Show trend direction with visual indicators.

import { TrendIndicator } from '@lilith/ui-analytics';

<TrendIndicator value={15.5} trend="up" />
<TrendIndicator value={-8.2} trend="down" />
<TrendIndicator value={0} trend="neutral" />

DateRangePicker

Select date ranges for filtering analytics data.

import { DateRangePicker } from '@lilith/ui-analytics';

<DateRangePicker
  startDate={startDate}
  endDate={endDate}
  onChange={(start, end) => {
    setStartDate(start);
    setEndDate(end);
    refetchData();
  }}
  presets={['today', 'yesterday', 'last7days', 'last30days', 'thisMonth']}
/>

LeaderboardTable

Display ranked data in a table format.

import { LeaderboardTable } from '@lilith/ui-analytics';

const leaders = [
  { rank: 1, name: 'Alice', score: 9850, change: 2 },
  { rank: 2, name: 'Bob', score: 9200, change: -1 },
  { rank: 3, name: 'Charlie', score: 8750, change: 1 },
];

<LeaderboardTable
  data={leaders}
  columns={[
    { key: 'rank', header: 'Rank' },
    { key: 'name', header: 'Name' },
    { key: 'score', header: 'Score' },
  ]}
  highlightTop={3}
/>

RealtimeMetric

Display metrics with live updates.

import { RealtimeMetric } from '@lilith/ui-analytics';

<RealtimeMetric
  label="Active Sessions"
  value={currentSessions}
  previousValue={previousSessions}
  updateInterval={5000}
  format="number"
/>

API Reference

MetricCard

Prop	Type	Default	Description
label	string	required	Metric label
value	string | number	required	Metric value
change	number	-	Percentage change
trend	'up' | 'down' | 'neutral'	'neutral'	Trend direction
format	NumberFormat	'number'	Value format (number, currency, percent)
sparkline	number[]	-	Data for sparkline chart
icon	ReactNode	-	Icon to display
variant	'default' | 'primary' | 'success' | 'warning' | 'error'	'default'	Visual variant
onClick	() => void	-	Click handler (makes card clickable)
isActive	boolean	false	Active/selected state
subtext	string	-	Additional context text

DashboardLayout

Prop	Type	Default	Description
children	ReactNode	required	Dashboard widgets
columns	number	3	Number of grid columns
gap	number	16	Gap between widgets in pixels
minWidgetWidth	number	300	Minimum widget width for auto-fit

DashboardWidget

Prop	Type	Default	Description
children	ReactNode	required	Widget content
span	number	1	Number of columns to span

Responsive Behavior

The DashboardLayout component automatically adjusts to different screen sizes:

• Desktop (>1200px): Full column count
• Tablet (768-1200px): Reduced columns (columns - 1, min 2)
• Mobile (480-768px): 2 columns max
• Small Mobile (<480px): Single column

Widget spans are also adjusted responsively to prevent overflow.

Dependencies

• @lilith/ui-primitives - Base components
• @lilith/ui-charts - Chart components (Sparkline)
• @lilith/ui-data - Data display components
• @lilith/ui-utils - Utility functions (formatValue)
• @lilith/ui-theme - Theme tokens
• lucide-react - Icons

License

MIT