Documentation

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: 'purchases',
  label: 'Purchases',
  event: 'purchase_completed',
  aggregation: 'count',
  trend: { enabled: true },
  sparkline: { enabled: true, type: 'line' },
})

Live queries support count and unique_users.

timeSeries

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

Time series use daily buckets in UTC. A day without matching events is shown as0 (for both count and unique_users, an empty day is exactly zero). The previous-period line uses the current range shifted back by as many whole UTC days as the range has buckets, and each previous value is drawn on the current day it aligns with. Tooltips and CSV exports keep the original previous-period date. Month ends need no calendar arithmetic and local daylight-saving changes cannot move buckets.

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' },
})

Category limits and totals

Breakdown, bar and pie widgets show the top limit categories by value.limit must be an integer from 1 to 100 (default 10; pie charts default to 6). Totals and percentages always use the true total for the widget's event, filters and metric, not the sum of the categories shown.

count: with showOther: true, an "All other categories" row holds the total minus the categories shown.
unique_users: a user can appear in several categories, so shares are of all users and don't add up to 100%. No "Other" row is created.
When more categories exist than are shown, the widget says it is partial.
Multi-series bar charts use each series' own total. A series value outside that series' top limit is left blank rather than shown as zero.
Pie minPercentage never drops data silently: small slices move into "All other categories" for counts with showOther, otherwise the widget reports how many were hidden.

CSV export

Every widget can copy or download its rows as CSV. Text that a spreadsheet would run as a formula (starting with =, +, -, @, a tab or a line break, also after leading spaces) is prefixed with '. Numbers stay numeric.

funnel

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

Current funnel query limit

Funnels require exactly two steps. Configurations with more or fewer steps are rejected.

Shared widget fields

id: unique widget ID
filter: per-widget filter expression (see how it combines with exploration filters)
dateRange: override dashboard date range
editable: enable UI edits
layout: grid placement (colSpan, rowSpan)