## Metric Card Widget

The Metric Card widget displays a single key performance indicator (KPI) with optional comparison indicators and sub-values. Perfect for highlighting the most important numbers in your reports.

### When to Use

- Display primary metrics at a glance (Revenue, Profit, Orders)
- Show progress with comparison to previous periods
- Create dashboard-style overviews with multiple metrics side-by-side
- Highlight goal achievement or performance indicators

#### Configuration Options

### Content Settings

### Title (Required)

What it is: The label displayed above the metric value

Examples: "Total Revenue", "Net Profit", "Order Count", "Profit Margin"

Tip: Keep titles short and descriptive (2-4 words ideal)

### Metric (Required)

What it is: The data point to display

Available metrics:

- Revenue metrics: Total Revenue, Gross Revenue, Net Revenue
- Profit metrics: Total Profit, Gross Profit, Net Profit, Profit Margin
- Order metrics: Order Count, Average Order Value, Completed Orders
- Cost metrics: Total Costs, Product Costs, Shipping Costs, Ad Spend
- Performance metrics: ROAS, Conversion Rate, Customer Count
- And many more...

How to select: Use the searchable dropdown to find your metric by typing keywords

### Change Indicator

What it is: Shows how current value compares to a reference period

Options:

- Previous Period: Compare to equivalent previous period
  - If viewing last 7 days → compare to prior 7 days
  - If viewing this month → compare to last month
- Previous Year: Compare to same period last year
- None: Don't show comparison

Display: Shows as percentage change with up/down arrow and color coding (green for increase in positive metrics, red for decrease)

### Sub Value

What it is: Small text displayed below the main metric

Options:

- Previous Period: Shows actual value from previous period
- Period Label: Shows the date range (e.g., "Last 30 Days")
- None: No sub-value

#### Design Settings

### Responsive Width

Desktop Columns (1-12): How many columns wide on desktop

- 3 columns = 4 cards per row
- 4 columns = 3 cards per row
- 6 columns = 2 cards per row
- 12 columns = full width

Tablet Columns (1-12): Width on tablet devices

Mobile Columns (1-12): Width on mobile (typically 12 for full width)

Recommended: 3 desktop, 6 tablet, 12 mobile for balanced layout

### Icon

What it is: Small icon displayed next to the title

Available icons:

- trending_up, trending_down (trends)
- attach_money, account_balance_wallet (financial)
- shopping_cart, inventory_2 (orders/products)
- people (customers)
- bar_chart, pie_chart (analytics)
- And 50+ more Material Icons

Default: trending_up

### Color Theme

What it is: Background color scheme for the card

Available themes:

- Blue (default) - Professional, trust
- Green - Success, profit, growth
- Red - Attention, alerts, costs
- Purple - Premium, special metrics
- Orange - Energy, engagement
- Gray - Neutral, secondary metrics

Tip: Use color consistently (e.g., green for profit, red for costs, blue for revenue)

#### Advanced Settings

### Enable Real-Time Data

What it is: Auto-refresh the metric at intervals

Options:

- Off (default): Static data from page load
- On: Refreshes every 30 seconds

When to use: For live dashboards or real-time monitoring

Note: May impact performance with many widgets

#### Example Configurations

#### Example 1: Revenue Card with Growth

    	Title: Total Revenue
    Metric: Total Revenue
    Change Indicator: Previous Period
    Sub Value: Previous Period
    Icon: attach_money
    Color: Blue
    Width: 3 (desktop), 6 (tablet), 12 (mobile)

Result: Shows current revenue, % change vs previous period, and previous period's value

#### Example 2: Profit Margin Tracker

    	Title: Profit Margin
    Metric: Profit Margin (%)
    Change Indicator: Previous Period
    Sub Value: Period Label
    Icon: trending_up
    Color: Green
    Width: 3 (desktop)

Result: Displays margin percentage with trend indicator

#### Example 3: Order Count Simple

    	Title: Orders
    Metric: Order Count
    Change Indicator: None
    Sub Value: Period Label
    Icon: shopping_cart
    Color: Purple
    Width: 3 (desktop)

Result: Clean order count without comparison

#### Example 4: ROAS Performance

    	Title: Return on Ad Spend
    Metric: ROAS
    Change Indicator: Previous Period
    Sub Value: Previous Period
    Icon: trending_up
    Color: Orange
    Width: 3 (desktop)

### Visual Examples

### Basic Display

    	┌─────────────────────┐
    │ [attach_money icon] │
    │  Total Revenue      │
    │                     │
    │     $45,230         │
    │    ↑ 12.5%          │
    │                     │
    │  vs $40,180 prior   │
    └─────────────────────┘

### With Negative Change

    	┌─────────────────────┐
    │ [bar_chart icon]    │
    │  Profit Margin      │
    │                     │
    │      28.5%          │
    │    ↓ 3.2%           │
    │                     │
    │  vs 31.7% prior     │
    └─────────────────────┘

#### Best Practices

### Layout Guidelines

- Dashboard Overview: Use 4 cards (3 columns each) at top of report for key metrics
- Card Hierarchy: Most important metric first (typically Profit or Revenue)
- Consistent Width: Keep all cards same width for visual balance
- Mobile-First: Always set mobile to 12 columns for readability

### Metric Selection

- Focus on Outcomes: Profit > Revenue, Conversion Rate > Traffic
- Limit Cards: 3-6 metric cards per report (avoid overwhelming users)
- Related Metrics: Group related cards together (all revenue metrics, all cost metrics)

### Comparison Settings

- Always Compare: Enable change indicators unless you have specific reason not to
- Previous Period: Most useful for spotting trends
- Previous Year: Good for seasonal businesses

### Color Usage

- Green: Profit, margin, positive growth metrics
- Blue: Revenue, orders, neutral metrics
- Red: Costs, expenses, alert metrics
- Purple: Special metrics, goals, targets
- Avoid: Random colors that don't convey meaning

#### Common Use Cases

### Executive Dashboard

4 cards at top of dashboard:

1. Net Profit (Green, 3 cols)
2. Total Revenue (Blue, 3 cols)
3. Order Count (Purple, 3 cols)
4. Profit Margin (Green, 3 cols)

#### Marketing Performance

1. Ad Spend (Red, 3 cols)
2. ROAS (Orange, 3 cols)
3. Conversion Rate (Blue, 3 cols)
4. Customer Acquisition Cost (Purple, 3 cols)

### Product Performance

1. Units Sold (Purple, 4 cols)
2. Average Profit per Unit (Green, 4 cols)
3. Product Margin (Green, 4 cols)

#### Troubleshooting

### Issue: No Data Showing

Check:

- Metric is available for your data source
- Date range includes orders/data
- Filters aren't excluding all data

#### Issue: Comparison Shows "N/A"

Cause: No data in previous period

Solution: Extend date range to include prior period data

### Issue: Card Too Small/Large

Solution: Adjust column widths for each device size

#### Issue: Icon Not Displaying

Solution: Icon name may be incorrect - select from dropdown rather than typing

### Related Widgets

- Metric List Widget - Display multiple metrics in one widget
- Line Chart Widget - Show metric trends over time
- Data Table Widget - Detailed metric breakdown