Widgets

Widget builders and key options

Available widget builders

Builder	Use case	Core fields
`widget.metric()`	Single KPI	label, event, aggregation
`widget.timeSeries()`	Trend over time	title, event/series, metric
`widget.breakdown()`	Top values by property	title, event, defaultBreakdown, metric
`widget.barChart()`	Category comparison	title, event, breakdownBy
`widget.pieChart()`	Part-to-whole	title, event, breakdownBy, variant
`widget.funnel()`	Step conversion	title, steps

metric

widget.metric({
  id: 'revenue',
  label: 'Revenue',
  event: 'purchase_completed',
  aggregation: 'sum',
  property: 'amount',
  trend: { enabled: true },
  sparkline: { enabled: true, type: 'line' },
})

Valid aggregation values: count, unique_users,sum, avg, min, max.

timeSeries

widget.timeSeries({
  id: 'traffic',
  title: 'Traffic',
  event: '$pageview',
  metric: 'count',
  chartType: 'area',
  granularity: 'day',
  smooth: true,
  comparison: { enabled: true },
})

breakdown

widget.breakdown({
  id: 'top_pages',
  title: 'Top Pages',
  event: '$pageview',
  defaultBreakdown: '$pathname',
  metric: 'count',
  limit: 10,
  showOther: true,
})

barChart

widget.barChart({
  id: 'devices',
  title: 'Devices',
  event: '$pageview',
  breakdownBy: '$device_type',
  metric: 'count',
  orientation: 'horizontal',
  showValues: true,
})

pieChart

widget.pieChart({
  id: 'sources',
  title: 'Sources',
  event: '$pageview',
  breakdownBy: '$referrer_domain',
  metric: 'count',
  variant: 'donut', // 'pie' | 'donut' | 'semi-donut'
  centerContent: { showTotal: true, subtitle: 'Total' },
})

funnel

widget.funnel({
  id: 'signup_funnel',
  title: 'Signup Funnel',
  steps: [
    { event: '$pageview', label: 'Viewed Site' },
    { event: 'signup_started', label: 'Started Signup' },
    { event: 'signup_completed', label: 'Completed Signup' },
  ],
  showConversionRates: true,
})

Current funnel query limit

Live query execution currently uses the first two funnel steps. Additional steps still compile, but runtime data is two-step today.

Shared widget fields

id: unique widget ID
filter: per-widget filter expression
dateRange: override dashboard date range
editable: enable UI edits
layout: grid placement (colSpan, rowSpan)