KPI & Chart Widgets

KPI tiles and chart widgets are the most commonly used widget types on NexusRMS dashboards. This article covers how each one works, its configuration options, the animation system, and best practices for choosing the right visualisation.

KPI widget

The KPI widget (kpi_tile) displays a single key metric as a large value with supporting context. Each tile shows:

• Primary value — The main metric number (e.g., £24,500 or 87%)
• Label — A descriptive title beneath the value (stored in widget_name)
• Trend arrow — An up, down, or neutral indicator showing the direction of change
• Percentage change — The magnitude of change compared to the selected comparison period
• Live pulse animation — A subtle visual pulse when the value updates in real time

KPI configuration options in the widget configuration object:

• kpi_type — The metric to display (e.g., total_revenue, active_projects, equipment_utilization, outstanding_invoices, overdue_invoices, available_equipment, pending_checkins, low_stock_alerts, crew_hours_worked)
• date_range — The period to calculate over (e.g., this_month, this_year, last_30_days)
• comparison_period — The period to compare against for trend calculation (e.g., previous_month, previous_year)
• show_trend — Whether to display the trend arrow (true/false)
• show_percentage_change — Whether to show the percentage change value (true/false)

KPI tiles are typically sized at 3 columns wide by 2 rows tall, fitting four tiles across the top of a 12-column dashboard.

Line Chart widget

The Line Chart (line_chart) visualises trends over time using the LineChartCalculator. It supports multiple data series plotted on a shared time axis, making it ideal for comparing metrics across periods.

• Common uses — Revenue trend over 12 months, project pipeline over time, equipment utilisation week by week
• Configuration — data_source, metric, group_by (day, week, month), date_range, compare_series (e.g., this year vs last year), show_trend_line
• Recommended size — Medium (6 columns) or large (12 columns) for readability

Bar Chart widget

The Bar Chart (bar_chart) compares values across discrete categories using the BarChartCalculator. It supports both grouped and stacked bar modes.

• Common uses — Profit by equipment category, equipment count by status, crew utilisation by member, aged receivables
• Configuration — data_source, metric, group_by, date_range, stacked mode toggle
• Recommended size — Medium to large depending on the number of categories

Donut and Pie Chart widget

The Donut/Pie Chart (donut_chart, pie_chart) displays proportional breakdowns. Both types share the PieChartCalculator — the only difference is visual (donut has a hollow centre).

• Common uses — Revenue by client, equipment status distribution, project status breakdown
• Configuration — data_source, metric, group_by, limit (max slices before grouping into “Other”), date_range
• Recommended size — Medium (6 columns) for optimal proportions

Area Chart widget

The Area Chart (area_chart) is a filled line chart ideal for cumulative or stacked data, calculated by AreaChartCalculator. Common uses include cumulative revenue and cash flow projections. Configuration matches the line chart with an additional fill opacity setting. Recommended size: medium to large.

Gauge Chart widget

The Gauge Chart (gauge_chart) displays a single metric as a speedometer dial against a min/max range, using GaugeChartCalculator. Common uses: payment collection rate, equipment utilisation percentage, quote conversion rate. Configure with metric, target (shown as a marker on the gauge), and date_range. Recommended size: small (4 columns).

Funnel, Scatter, Heat Map, and Combo Charts

The remaining chart types are all included in the base plan — no addon required:

• Funnel Chart (funnel_chart) — Multi-stage conversion flows (e.g., Quote → Confirmed → Invoiced → Paid). Uses FunnelChartCalculator. Configure with a stages array and show_conversion_rates. Best at medium size (6 columns).
• Scatter Chart (scatter_chart) — Correlation analysis across two axes (e.g., project profitability vs size). Uses ScatterPlotCalculator. Configure with x_axis_metric, y_axis_metric, and data_source. Best at medium to large size.
• Heat Map (heat_map) — Colour-coded grid for pattern identification (e.g., equipment availability by day and category). Uses HeatMapCalculator. Configure with x_axis, y_axis, and metric. Best at full width (12 columns).
• Combo Chart (combo_chart) — Overlays bar and line series on the same axes (e.g., revenue vs expenses). Uses ComboChartCalculator. Configure primary_series and secondary_series with type, data source, and metric. Best at medium to large size.

Widget animations

The useWidgetAnimation composable provides visual feedback when widget data updates. Four animation types are available:

• Pulse — A subtle scale animation (the widget briefly grows to 1.02x and returns)
• Flash — The widget background briefly highlights with the primary theme colour
• Slide — Content slides up 4 pixels with a fade-in effect
• Highlight — A 2-pixel box shadow appears momentarily around the widget border

Additional animations are applied to specific elements within widgets:

• Value pop — The numeric value briefly scales to 1.05x and flashes the primary colour when it changes
• Trend bounce — The trend indicator arrow bounces 4 pixels upward when the direction changes
• Live pulse — A green dot beside the widget title continuously pulses to indicate active real-time updates

Animations are debounced at 100 milliseconds by default to handle rapid data changes gracefully, with a total animation duration of 800 milliseconds.

Chart.js integration

All chart widgets render through Chart.js with the following shared behaviours:

• Responsive sizing — Charts resize automatically when the widget or browser window changes size
• Interactive tooltips — Hover over any data point to see its exact value and label
• Animated transitions — Data changes animate smoothly rather than snapping to new values
• Configurable legends — Toggle legend visibility in widget settings

Tips for choosing the right widget

• Single metric at a glance — Use a KPI tile
• Trends over time — Use a line chart or area chart
• Category comparisons — Use a bar chart
• Proportional breakdowns — Use a donut or pie chart
• Target vs actual — Use a gauge chart for a single metric, or a combo chart for time-series comparison
• Conversion flows — Use a funnel chart
• Pattern discovery — Use a heat map for two-dimensional patterns, or a scatter chart for correlations
• Multiple metrics together — Use a combo chart to overlay different data types