Report Viewer

Renders a report definition JSON into a fully interactive view. Fetches datasources, evaluates expressions, and provides a rich set of viewer features including sorting, drill-through, PDF export, and parameter filtering.

A multi-section sales report featuring header, subtitle, horizontal rules, bar/donut/line/pie charts in a 2-column layout, a sortable detail table with copy-to-clipboard, and a disclaimer footer. A4 page setup with 10mm margins. Use the toolbar to test Print and PDF Export. Switch tabs to inspect the definition JSON and raw datasource data.

Quarterly Sales Report

FY 2025 — Regional sales performance across product lines and quarters.

Revenue Overview

Detailed Transactions

Click column headers to sort. Use "Copy Data" to export to clipboard.

Region	Product	Quarter	Revenue ($)	Units Sold
North	Widget A	Q1	12500	150
North	Widget B	Q1	8200	90
North	Widget A	Q2	14100	170
North	Widget B	Q2	9500	105
South	Widget A	Q1	15800	200
South	Widget B	Q1	6400	75
South	Widget A	Q2	16200	210
South	Widget B	Q2	7800	88
East	Widget A	Q1	11000	130
East	Widget B	Q1	9700	110
East	Widget A	Q2	12400	145
East	Widget B	Q2	10200	118
West	Widget A	Q1	14200	180
West	Widget B	Q1	7100	85
West	Widget A	Q2	15600	195
West	Widget B	Q2	8400	96

Disclaimer: This report contains sample data for demonstration purposes only. Revenue figures are fictional and do not represent actual business performance. Generated by FluxoUI Report Viewer.

Import

// Base styles (once in your app entry)
import 'fluxo-ui/styles';

// Report Viewer component and types
import { ReportViewer } from 'fluxo-ui/report-builder';
import type {
  ReportDefinition,
  ReportViewerProps,
  ReportViewerHandle,
  DatasourcePlugin,
  SubReportDefinition,
} from 'fluxo-ui/report-builder';

Basic Usage

<ReportViewer
  definition={reportJson}
  datasourcePlugins={[myPlugin]}
  parameterValues={{ year: 2025, region: 'US' }}
  onParameterChange={(values) => setParams(values)}
  parameterPanel={{ mode: 'docked', position: 'left' }}
  onColumnResize={(compId, colId, w) => persist(compId, colId, w)}
  onDrillThrough={(param, value) => console.log(param, value)}
  syncParamsToHash
/>

// Custom toolbar with viewerRef:
const viewerRef = useRef<ReportViewerHandle>(null);

<ReportViewer
  definition={reportJson}
  datasourcePlugins={[myPlugin]}
  hideToolbar
  viewerRef={viewerRef}
/>
<button onClick={() => viewerRef.current?.print()}>Print</button>
<button onClick={() => viewerRef.current?.exportPdf()}>PDF</button>
<button onClick={() => viewerRef.current?.refresh()}>Reload</button>

ReportViewer Props

PropertyTypeDefaultDescription

definitionreq

ReportDefinition

—

The report definition JSON to render.

definitionreq

ReportDefinition

The report definition JSON to render.

datasourcePluginsreq

DatasourcePlugin[]

—

Plugins used to fetch datasource data.

datasourcePluginsreq

DatasourcePlugin[]

Plugins used to fetch datasource data.

parameterValues

Record<string, unknown>

—

Controlled parameter values.

parameterValues

Record<string, unknown>

Controlled parameter values.

onParameterChange

(values: Record<string, unknown>) => void

—

Fires when end-user changes parameter values.

onParameterChange

(values: Record<string, unknown>) => void

Fires when end-user changes parameter values.

parameterPanel

{ mode: "popover" | "docked"; position?: "left" | "right" | "top" }

—

Parameter panel display mode and position.

parameterPanel

{ mode: "popover" | "docked"; position?: "left" | "right" | "top" }

Parameter panel display mode and position.

subReportDefinitions

SubReportDefinition[]

—

Available sub-report definitions for recursive rendering.

subReportDefinitions

SubReportDefinition[]

Available sub-report definitions for recursive rendering.

onColumnResize

(componentId, columnId, width) => void

—

Fires when user resizes a table column.

onColumnResize

(componentId, columnId, width) => void

Fires when user resizes a table column.

onColumnReorder

(componentId, columnIds) => void

—

Fires when user reorders table columns via drag.

onColumnReorder

(componentId, columnIds) => void

Fires when user reorders table columns via drag.

onDrillThrough

(parameterName, value) => void

—

Fires when user clicks a table row or chart element for drill-through.

onDrillThrough

(parameterName, value) => void

Fires when user clicks a table row or chart element for drill-through.

onCellEdit

(componentId, rowIndex, field, value) => void

—

Fires when user edits a table cell (double-click to edit).

onCellEdit

(componentId, rowIndex, field, value) => void

Fires when user edits a table cell (double-click to edit).

syncParamsToHash

boolean

false

Sync parameter values to URL hash for bookmarkable state.

syncParamsToHash

booleanfalse

Sync parameter values to URL hash for bookmarkable state.

hideToolbar

boolean

false

Hide the built-in toolbar. Use with viewerRef to provide your own controls.

hideToolbar

booleanfalse

Hide the built-in toolbar. Use with viewerRef to provide your own controls.

viewerRef

React.Ref<ReportViewerHandle>

—

Ref to access viewer actions (exportPdf, print, refresh) from external buttons.

viewerRef

React.Ref<ReportViewerHandle>

Ref to access viewer actions (exportPdf, print, refresh) from external buttons.

className

string

—

Additional CSS class.

className

string

Additional CSS class.

style

CSSProperties

—

Inline styles.

style

CSSProperties

Inline styles.

Callback Reference

onColumnResize

(componentId: string, columnId: string, width: number) => void

Persist column widths back to your definition store. Fires on every drag resize.

onColumnReorder

(componentId: string, columnIds: string[]) => void

Persist column order. Fires when user drag-reorders table headers.

onDrillThrough

(parameterName: string, value: unknown) => void

Fires when user clicks a table row or chart element. The row object or data point is passed as value. Parameter values are auto-updated internally.

onCellEdit

(componentId: string, rowIndex: number, field: string, value: unknown) => void

Fires when user double-clicks a cell and commits an edit. Only works when enableCellEdit is true on the table component.

onParameterChange

(values: Record<string, unknown>) => void

Fires when end-user changes any parameter value via the parameter panel or drill-through.

Features

Datasource Fetching

Automatically fetches all datasources on mount via plugins. Derived datasources processed sequentially after regular ones.

Expression Evaluation

Evaluates dynamic expressions in text, visibility, formatting, and conditional styles at render time.

Parameter Panel

Docked or popover parameter panel lets end-users filter and configure reports interactively.

Table Features

Sorting, grouping (multi-level), pivot mode, frozen columns, column resizing, reorder, conditional formatting, inline editing.

Chart Rendering

Bar (stacked), Line (tension, area fill), Pie, and Donut charts via Chart.js with responsive layout.

PDF Export & Print

Export to PDF via html2canvas or print with dedicated print stylesheet and proper page breaks.

Drill-through

Click table rows or chart elements to filter other components by updating parameter values.

Virtual Scrolling

Automatic virtual scrolling for tables with 100+ rows. Only visible rows render.

Sub-reports

Recursive rendering of nested sub-reports with their own datasources and parameter mappings.

Copy to Clipboard

One-click copy of filtered table data as tab-separated values.

URL Bookmarking

Optional parameter state sync to URL hash for shareable/bookmarkable report views.

Canvas Layout

Absolute-positioned free-form canvas with component rendering.