Dashboard Card Types

Alloy supports 18 different card types that can be rendered in your dashboard. Each card type has a specific structure in the spec and data_preview fields that you can use to render them on your own platform.

Card Type Overview

The following card types are available:

bar - Bar Chart
line - Line Chart
area - Area Chart
pie - Pie Chart
donut - Donut Chart
table - Data Table
kpi - KPI Card
insight - AI Insight (textual insights)
heatmap - Heatmap
scatter - Scatter Plot
bubble - Bubble Chart
histogram - Histogram
boxplot - Box Plot
radar - Radar Chart
funnel - Funnel Chart
gauge - Gauge
geomap - Geo Map
choropleth - Choropleth Map

Common Structure

All card types share the same base structure:

{
  "id": "uuid",
  "type": "card_type",
  "title": "Card Title",
  "description": "Card description",
  "spec": {
    // Type-specific configuration
  },
  "data_preview": {
    "columns": ["column1", "column2"],
    "rows": [
      {"column1": "value1", "column2": 123}
    ],
    "x_axis": "X Axis Label",
    "y_axis": "Y Axis Label",
    "grouping_axis": "Grouping Label"
  },
  "position": 0
}

Card Type Specifications

Bar Chart (bar)

Spec Fields:

x (string, required): Field name for x-axis/categories
y (string, required): Field name for y-axis/values
aggregation (string, optional): Aggregation function (sum, avg, count, min, max)
grouping (string, optional): Field name for grouping/series
color (string, optional): Field name for color encoding

Example:

{
  "type": "bar",
  "title": "Revenue by Region",
  "spec": {
    "x": "region",
    "y": "revenue",
    "aggregation": "sum"
  },
  "data_preview": {
    "columns": ["region", "revenue"],
    "rows": [
      {"region": "West", "revenue": 450000},
      {"region": "East", "revenue": 380000}
    ],
    "x_axis": "Region",
    "y_axis": "Revenue"
  }
}

Line Chart (line)

Spec Fields:

x (string, required): Field name for x-axis (typically time)
y (string, required): Field name for y-axis/values
aggregation (string, optional): Aggregation function
grouping (string, optional): Field name for multiple series

Example:

{
  "type": "line",
  "title": "Sales Over Time",
  "spec": {
    "x": "month",
    "y": "sales",
    "aggregation": "sum",
    "grouping": "region"
  },
  "data_preview": {
    "columns": ["month", "sales", "region"],
    "rows": [
      {"month": "2025-01", "sales": 120000, "region": "West"},
      {"month": "2025-02", "sales": 135000, "region": "West"}
    ],
    "x_axis": "Month",
    "y_axis": "Sales"
  }
}

Area Chart (area)

Spec Fields:

x (string, required): Field name for x-axis
y (string, required): Field name for y-axis/values
aggregation (string, optional): Aggregation function
stacked (boolean, optional): Whether to stack areas

Example:

{
  "type": "area",
  "title": "Revenue Trend",
  "spec": {
    "x": "date",
    "y": "revenue",
    "aggregation": "sum",
    "stacked": true
  },
  "data_preview": {
    "columns": ["date", "revenue"],
    "rows": [
      {"date": "2025-01-01", "revenue": 50000},
      {"date": "2025-01-02", "revenue": 55000}
    ],
    "x_axis": "Date",
    "y_axis": "Revenue"
  }
}

Pie Chart (pie)

Spec Fields:

values (string, required): Field name for values
grouping (string, required): Field name for categories
aggregation (string, optional): Aggregation function

Example:

{
  "type": "pie",
  "title": "Sales by Category",
  "spec": {
    "values": "sales",
    "grouping": "category",
    "aggregation": "sum"
  },
  "data_preview": {
    "columns": ["category", "sales"],
    "rows": [
      {"category": "Electronics", "sales": 250000},
      {"category": "Clothing", "sales": 180000}
    ],
    "grouping_axis": "Category"
  }
}

Donut Chart (donut)

Spec Fields:

values (string, required): Field name for values
grouping (string, required): Field name for categories
aggregation (string, optional): Aggregation function
inner_radius (number, optional): Inner radius ratio (0-1)

Example:

{
  "type": "donut",
  "title": "Market Share",
  "spec": {
    "values": "market_share",
    "grouping": "company",
    "aggregation": "sum",
    "inner_radius": 0.45
  },
  "data_preview": {
    "columns": ["company", "market_share"],
    "rows": [
      {"company": "Company A", "market_share": 35},
      {"company": "Company B", "market_share": 28}
    ],
    "grouping_axis": "Company"
  }
}

Table (table)

Spec Fields:

columns (array, required): Array of column definitions
- Each column: {"key": "field_name", "label": "Display Label"}
sorted_by (string, optional): Field name to sort by
sort_direction (string, optional): asc or desc
limit (number, optional): Maximum rows to display

Example:

{
  "type": "table",
  "title": "Sales Data",
  "spec": {
    "columns": [
      {"key": "region", "label": "Region"},
      {"key": "sales", "label": "Sales"},
      {"key": "date", "label": "Date"}
    ],
    "sorted_by": "sales",
    "sort_direction": "desc",
    "limit": 10
  },
  "data_preview": {
    "columns": ["region", "sales", "date"],
    "rows": [
      {"region": "West", "sales": 450000, "date": "2025-01-15"},
      {"region": "East", "sales": 380000, "date": "2025-01-15"}
    ]
  }
}

KPI Card (kpi)

Spec Fields:

value (number, required): The KPI value
value_from_column (string, optional): Source column name
operation (string, optional): Operation used (sum, mean, count, min, max)
unit (string, optional): Unit of measurement (e.g., "$", "%", "hrs")
trend (string, optional): Trend indicator (e.g., "+12% vs last month")
target (number, optional): Target value

Example:

{
  "type": "kpi",
  "title": "Total Revenue",
  "spec": {
    "value": 1250000,
    "value_from_column": "revenue",
    "operation": "sum",
    "unit": "$",
    "trend": "+12% vs last month",
    "target": 1000000
  },
  "data_preview": {
    "columns": ["label", "value"],
    "rows": [
      {"label": "Total Revenue", "value": 1250000}
    ]
  }
}

AI Insight (insight)

Spec Fields:

Empty object {} (no spec fields)

Description Field:

Contains the AI-generated insight text

Example:

{
  "type": "insight",
  "title": "AI Insight",
  "description": "Revenue increased 23% compared to last quarter. Top performing region is West with $450K in sales.",
  "spec": {},
  "data_preview": {}
}

Heatmap (heatmap)

Spec Fields:

x (string, required): Field name for x-axis
y (string, required): Field name for y-axis
color (string, required): Field name for color intensity
aggregation (string, optional): Aggregation function

Example:

{
  "type": "heatmap",
  "title": "Sales by Region and Month",
  "spec": {
    "x": "month",
    "y": "region",
    "color": "sales",
    "aggregation": "sum"
  },
  "data_preview": {
    "columns": ["month", "region", "sales"],
    "rows": [
      {"month": "2025-01", "region": "West", "sales": 450000},
      {"month": "2025-01", "region": "East", "sales": 380000}
    ],
    "x_axis": "Month",
    "y_axis": "Region",
    "grouping_axis": "Sales"
  }
}

Scatter Plot (scatter)

Spec Fields:

x (string, required): Field name for x-axis
y (string, required): Field name for y-axis
color (string, optional): Field name for color encoding
size_by (string, optional): Field name for point size

Example:

{
  "type": "scatter",
  "title": "Price vs Volume",
  "spec": {
    "x": "price",
    "y": "volume",
    "color": "category",
    "size_by": "revenue"
  },
  "data_preview": {
    "columns": ["price", "volume", "category", "revenue"],
    "rows": [
      {"price": 100, "volume": 500, "category": "A", "revenue": 50000},
      {"price": 150, "volume": 300, "category": "B", "revenue": 45000}
    ],
    "x_axis": "Price",
    "y_axis": "Volume"
  }
}

Bubble Chart (bubble)

Spec Fields:

x (string, required): Field name for x-axis
y (string, required): Field name for y-axis
size_by (string, required): Field name for bubble size
color (string, optional): Field name for color encoding

Example:

{
  "type": "bubble",
  "title": "Market Analysis",
  "spec": {
    "x": "market_share",
    "y": "growth_rate",
    "size_by": "revenue",
    "color": "region"
  },
  "data_preview": {
    "columns": ["market_share", "growth_rate", "revenue", "region"],
    "rows": [
      {"market_share": 25, "growth_rate": 15, "revenue": 500000, "region": "West"}
    ],
    "x_axis": "Market Share",
    "y_axis": "Growth Rate"
  }
}

Histogram (histogram)

Spec Fields:

x (string, required): Field name for x-axis (numeric field)
aggregation (string, optional): Usually count
bin_size (number, optional): Size of bins

Example:

{
  "type": "histogram",
  "title": "Age Distribution",
  "spec": {
    "x": "age",
    "aggregation": "count",
    "bin_size": 5
  },
  "data_preview": {
    "columns": ["bucket", "count"],
    "rows": [
      {"bucket": "20-25", "count": 45},
      {"bucket": "25-30", "count": 62}
    ],
    "x_axis": "Age Range",
    "y_axis": "Count"
  }
}

Box Plot (boxplot)

Spec Fields:

grouping (string, required): Field name for groups
values (string, required): Field name for values

Example:

{
  "type": "boxplot",
  "title": "Sales by Region",
  "spec": {
    "grouping": "region",
    "values": "sales"
  },
  "data_preview": {
    "columns": ["region", "quartiles"],
    "rows": [
      {
        "region": "West",
        "quartiles": {
          "min": 100000,
          "q1": 200000,
          "median": 300000,
          "q3": 400000,
          "max": 500000
        }
      }
    ],
    "grouping_axis": "Region",
    "y_axis": "Sales"
  }
}

Radar Chart (radar)

Spec Fields:

axes (array, required): Array of axis names

Example:

{
  "type": "radar",
  "title": "Performance Scorecard",
  "spec": {
    "axes": ["quality", "cost", "speed", "risk", "satisfaction"]
  },
  "data_preview": {
    "columns": ["axis", "score"],
    "rows": [
      {"axis": "Quality", "score": 0.85},
      {"axis": "Cost", "score": 0.72},
      {"axis": "Speed", "score": 0.68}
    ]
  }
}

Funnel Chart (funnel)

Spec Fields:

steps (array, required): Array of step objects
- Each step: {"label": "Step Name", "value": number}

Example:

{
  "type": "funnel",
  "title": "Sales Pipeline",
  "spec": {
    "steps": [
      {"label": "Leads", "value": 1000},
      {"label": "Qualified", "value": 750},
      {"label": "Proposals", "value": 500},
      {"label": "Closed", "value": 250}
    ]
  },
  "data_preview": {
    "columns": ["stage", "value"],
    "rows": [
      {"stage": "Leads", "value": 1000},
      {"stage": "Qualified", "value": 750}
    ]
  }
}

Gauge (gauge)

Spec Fields:

value (number, required): Current value
min (number, optional): Minimum value
max (number, optional): Maximum value
target (number, optional): Target value
units (string, optional): Unit of measurement

Example:

{
  "type": "gauge",
  "title": "SLA Compliance",
  "spec": {
    "value": 78,
    "min": 0,
    "max": 100,
    "target": 85,
    "units": "%"
  },
  "data_preview": {
    "columns": ["label", "value"],
    "rows": [
      {"label": "SLA Compliance", "value": 78}
    ]
  }
}

Geo Map (geomap)

Spec Fields:

region_field (string, required): Field name containing region codes (e.g., country codes)
value_field (string, required): Field name for values
geo_scope (string, optional): Geographic scope (world, country, etc.)

Example:

{
  "type": "geomap",
  "title": "Sales by Country",
  "spec": {
    "region_field": "country_code",
    "value_field": "sales",
    "geo_scope": "world"
  },
  "data_preview": {
    "columns": ["country_code", "sales"],
    "rows": [
      {"country_code": "US", "sales": 500000},
      {"country_code": "GB", "sales": 300000}
    ],
    "grouping_axis": "Country"
  }
}

Choropleth Map (choropleth)

Spec Fields:

region_field (string, required): Field name containing region codes
value_field (string, required): Field name for values
geo_scope (string, optional): Geographic scope (e.g., nigeria, usa, world)
color_scale (string, optional): Color scale name (e.g., Blues, Reds)

Example:

{
  "type": "choropleth",
  "title": "Sales by State",
  "spec": {
    "region_field": "state_code",
    "value_field": "sales",
    "geo_scope": "nigeria",
    "color_scale": "Blues"
  },
  "data_preview": {
    "columns": ["state_code", "sales"],
    "rows": [
      {"state_code": "LA", "sales": 400000},
      {"state_code": "FC", "sales": 180000}
    ],
    "grouping_axis": "State"
  }
}

Rendering Guidelines

General Approach

Sort by Position

Always render chart_blocks in order of their position field.

Use Data Preview

The data_preview field contains the processed data ready for rendering — use it as the source for visuals.

Respect Spec

The spec field contains configuration that should guide your rendering (axes, aggregations, grouping, etc.).

Handle Missing Data

Some fields may be optional — handle missing/optional fields gracefully in your UI (fallbacks, defaults, or hiding unsupported options).

Recommended Libraries

Charts: Chart.js, D3.js, Recharts, Plotly.js, Apache ECharts
Tables: Built-in HTML tables, DataTables, AG Grid
Maps: Leaflet, Mapbox, Google Maps API
KPIs: Custom components or libraries like react-gauge-chart

Example Rendering Flow

// Pseudocode example
const dashboard = await fetchDashboard(dashboardId);

// Sort blocks by position
const sortedBlocks = dashboard.chart_blocks.sort((a, b) => a.position - b.position);

// Render each block
sortedBlocks.forEach(block => {
  switch(block.type) {
    case 'kpi':
      renderKPICard(block);
      break;
    case 'bar':
      renderBarChart(block);
      break;
    case 'insight':
      renderInsight(block);
      break;
    // ... handle all 18 types
  }
});

If you want, I can:

Convert each card type section into reusable snippets (for quick copy/paste).
Provide example React/Chart.js or D3 renderers for one or more card types.

PreviousRetrieve Dashboard NextWebhooks

hashtagCard Type Overview

hashtagCommon Structure

hashtagCard Type Specifications

hashtagBar Chart (bar)

hashtagLine Chart (line)

hashtagArea Chart (area)

hashtagPie Chart (pie)

hashtagDonut Chart (donut)

hashtagTable (table)

hashtagKPI Card (kpi)

hashtagAI Insight (insight)

hashtagHeatmap (heatmap)

hashtagScatter Plot (scatter)

hashtagBubble Chart (bubble)

hashtagHistogram (histogram)

hashtagBox Plot (boxplot)

hashtagRadar Chart (radar)

hashtagFunnel Chart (funnel)

hashtagGauge (gauge)

hashtagGeo Map (geomap)

hashtagChoropleth Map (choropleth)

hashtagRendering Guidelines

hashtagGeneral Approach

hashtagSort by Position

hashtagUse Data Preview

hashtagRespect Spec

hashtagHandle Missing Data

hashtagRecommended Libraries

hashtagExample Rendering Flow

Card Type Overview

Common Structure

Card Type Specifications

Bar Chart (bar)

Line Chart (line)

Area Chart (area)

Pie Chart (pie)

Donut Chart (donut)

Table (table)

KPI Card (kpi)

AI Insight (insight)

Heatmap (heatmap)

Scatter Plot (scatter)

Bubble Chart (bubble)

Histogram (histogram)

Box Plot (boxplot)

Radar Chart (radar)

Funnel Chart (funnel)

Gauge (gauge)

Geo Map (geomap)

Choropleth Map (choropleth)

Rendering Guidelines

General Approach

Sort by Position

Use Data Preview

Respect Spec

Handle Missing Data

Recommended Libraries

Example Rendering Flow