API Reference · React

Public exports of @meterry/component-react. All components also support the className / classNames / unstyled and messages props (see Theming & Styles and Internationalization).

MeterClientProvider

Application-level shared client:

<MeterClientProvider tokenEndpoint="/api/meter/subject-token" options={{ credentials: 'include' }}>
  ...
</MeterClientProvider>

Prop	Description
client	Reuse an existing SubjectClient (takes precedence)
getJwt	Token callback used to create the shared client (unless client is supplied; precedes tokenEndpoint)
tokenEndpoint	Application-owned token GET route, used when client / getJwt are absent
options	MeterClientOptions for client creation (baseUrl / credentials / fetch / tokenStorageKey…)

useMeterClient(): SubjectClient | null — returns the shared client inside a Provider.

Automatic usage components

Configure tokenEndpoint on the shared provider to authenticate the automatic usage components. See Getting Started.

• MeterUsageTable: client / source / query / rangeDays / optional columns / pageSize / pageSizeOptions / batchSize / maxCachedRows / refreshable, plus table presentation, slots, messages and styles. No data, load or controller required. Guide and full props.
• MeterUsageChart: client / type / mode / query / rangeDays / measure / limit / cacheTimeMs / allowPartial / refreshable / formatValue, plus chart presentation, slots, messages, seriesRegistry and styles. No data, x or series required. Guide and full props.

Queries use snake_case API names (start_time, group_by), not MeterUsage’s UsageWidgetQuery camelCase. Default charts hide potentially truncated results; aggregate tables warn at the limit. Events automatically continue using cursors and use custom raw_event_id columns with the current Meter API. The original components below remain supported.

React additionally exports MeterUsageTableProps and MeterUsageChartProps.

MeterUsage

See the MeterUsage guide. Props: client / getJwt / tokenScope / tokenStorageKey / baseUrl / query / rangeDays / title / measure / loading / empty / error / onError / slots / messages / seriesRegistry + style props.

MeterUsageSlots: header({ caption, title }), value({ total, formattedTotal, measure }), chart({ model, option }).

MeterChart

See the MeterChart guide. Props are core’s ChartOptions<T> (type / data / x / series / title / height / showLegend / showGrid / theme) + caption / slots / messages / seriesRegistry + style props.

MeterChartSlots: header({ caption, title }), chart({ model, option }).

MeterTable

See the MeterTable guide. Props: columns (required) / data / load / controller / pageSize / pageSizeOptions / title / caption / empty / loading / error / slots / messages + style props.

MeterTableSlots<T>: header({ caption, title, description? }), toolbar({ filters, controller }), cell({ value, row, index, column }), pagination({ state, controller }).

Previously loaded rows remain visible during a reload. If loading fails, the table shows an error alongside those rows. Use controller.refresh() to offer a Retry action. See loading, failures, and retry.

MeterFilterBar

Standalone shared-filter UI. See Shared Filters for complete dashboard and controlled-mode examples.

Prop	Description
definitions	MeterFilterDefinition[]; defaults to the controller’s definitions or []
controller	MeterFilterController; takes precedence over values
values	MeterFilterValues; page-owned values without a controller
onChange	Receives the next full record in controlled/standalone modes; controller mode uses subscriptions instead
debounceMs	Text/number delay in milliseconds, default 300; set 0 to apply changes immediately; select changes apply immediately
messages	Partial<MeterMessages> including filterBarLabel, clearFilters, allFilterOption, filterPlaceholder

Style props: className / classNames / unstyled. Relevant slots: filterBar, filter, and button. Without a controller or values, the component maintains internal state. Defaults in definitions are applied by createMeterFilterController, not by a standalone bar.

Text and number filters apply after you pause typing; selects apply immediately without submitting unfinished input in other fields. Clear removes all shared filters. See applying and clearing filters.

useMeterFilters

useMeterFilters(controller: MeterFilterController): MeterFilterValues — reads current values, subscribes to changes, resubscribes when the controller changes, and removes the subscription on cleanup. Keep the controller stable with useMemo and treat returned values as read snapshots; write through controller methods.

Import createMeterFilterController, mergeMeterFilters, and normalizeMeterFilters from @meterry/component, not the React package.

registerEChartsSeries

On top of core, the framework package’s registerEChartsSeries also supports modules to load the required echarts modules when registering a custom type:

import { ScatterChart } from 'echarts/charts'
import { registerEChartsSeries } from '@meterry/component-react'

registerEChartsSeries(
  'scatter',
  (series) => ({ type: 'scatter', data: series.points.map((p) => p.value) }),
  { modules: [ScatterChart] },
)

unregisterEChartsSeries(type) is also re-exported from core. The EChartsModuleInstaller type represents any module accepted by echarts/core’s use().

Type re-exports

MeterClassNames, MeterComponentProps, MeterMessages, MeterPaginationInfo, ChartOptions, TableColumn, TableOptions, TableSort, MeterUsageProps, MeterChartProps<T>, MeterTableProps<T>, MeterFilterBarProps, MeterFilterController, MeterFilterDefinition, MeterFilterValues, and the slot context types.

MeterList / MeterUsageList

See the Load-more List guide. MeterList accepts data, load, controller, required columns: TableColumn<T>[], pageSize, rowKey, title, caption, empty, loading, error, refreshable, slots, messages and style props. Its footer appends with Load more, disables pending work, retries failures and stops at the end; rows from earlier pages remain visible.

MeterUsageList replaces application data/loading props with client, source (default events), query, rangeDays=7, pageSize=20, batchSize=500 and refreshable=true. It uses the shared Meter client/provider and automatic table transport, including cursor continuation and aggregate limit warnings. Default event columns use raw_event_id; optional columns replaces the defaults.

MeterListSlots<T> supports header, cell({ value, row, index, column }) and footer({ state, controller }). List renders an actual table with one shared column header, including loading/empty/error states. It reuses Table accessors, formatters, widths, alignment and table styles. The header slot is the title region, not the column header. Sort/filter controls are not provided. React exports MeterListProps<T> and MeterUsageListProps; Vue also supports native scoped slots and exposes loadMore() / refresh() through refs. The list controller does not dispose a caller-owned controller on unmount.