Ga naar hoofdinhoud

CnChartWidget

ApexCharts wrapper for dashboard and detail page widgets. Supports area, line, bar, pie, donut, and radialBar chart types with Nextcloud-themed defaults. The chart library is a peer dependency — consuming apps must install apexcharts and vue-apexcharts.

Try it​

Loading CnChartWidget playground…

Usage​

<!-- Area chart with categories -->
<CnChartWidget
  type="area"
  :series="[{ name: 'Requests', data: [10, 41, 35, 51, 49, 62] }]"
  :categories="['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']"
  :height="250" />

<!-- Pie chart -->
<CnChartWidget
  type="pie"
  :series="[44, 55, 13, 33]"
  :labels="['Active', 'Pending', 'Closed', 'Draft']" />

<!-- Bar chart with custom options -->
<CnChartWidget
  type="bar"
  :series="barSeries"
  :options="{ plotOptions: { bar: { horizontal: true } } }" />

When ApexCharts is not available a fallback slot or unavailableLabel is shown:

<CnChartWidget type="area" :series="series">
  <template #fallback>
    <p>Charts require the apexcharts package.</p>
  </template>
</CnChartWidget>

When CnDashboardPage resolves a widget definition with type: "chart", it mounts CnChartWidget automatically. Manifest authors do NOT mount this component themselves — declare a chart widget in pages[].config.widgets[] instead:

{
  "id": "sla-trend",
  "title": "myapp.sla_trend",
  "type": "chart",
  "props": {
    "chartKind": "line",
    "series": [{ "name": "SLA %", "data": [82, 88, 91, 93] }],
    "categories": ["Q1", "Q2", "Q3", "Q4"],
    "options": { "stroke": { "width": 3 } }
  }
}

The dispatcher forwards props.chartKind as the apex type and passes through series, categories, labels, options, colors, toolbar, legend, height, width, unavailableLabel.

dataSource — resolving series + categories from OpenRegister​

CnChartWidget accepts a dataSource block that resolves series / categories / labels from a GraphQL query against OpenRegister. Three shapes are supported:

Count shorthand​

dataSource: {
  schema: 'meeting',
  filter: { lifecycle: 'review' },
  aggregate: 'count',
}
// → { count: 4 } (use the raw `graphql:` form for chart series)

Bucket shorthand (time series)​

Emits OpenRegister's groupBy argument with a time interval and returns { series, categories } ready to feed into a line/bar chart:

dataSource: {
  schema: 'call_log',
  filter: { status: 'error' },
  bucket: {
    field: 'created',
    interval: 'day',                  // case-insensitive → DAY
    fromVar: 'from',                  // default 'from'
    toVar: 'to',                      // default 'to'
    staticRange: {                    // fallback when no dashboard range
      from: '2026-05-01T00:00:00.000Z',
      to:   '2026-05-22T00:00:00.000Z',
    },
  },
}

When mounted under a CnDashboardPage with dateRange.enabled, the widget injects cnDashboardDateRange and uses the dashboard's currently-selected { from, to } for the GraphQL variables — every chart on the page tracks the same range. If no dashboard range is available the widget falls back to bucket.staticRange; if neither is available no query is fired and the chart shows its fallback / unavailable state.

Non-count metrics are supported via metric ('sum' | 'avg' | 'min' | 'max', case-insensitive) + a required metricField:

bucket: {
  field: 'created',
  interval: 'week',
  metric: 'sum',
  metricField: 'amount',
  staticRange: { from: '…', to: '…' },
}

Raw GraphQL​

dataSource: {
  graphql: {
    query: 'query { meeting { groups { key value } } }',
    selectors: {
      series:     'meeting.groups[].value',
      categories: 'meeting.groups[].key',
    },
  },
}

The selector path syntax supports dot-paths with optional [] flat-maps. See selectByPath for the full path grammar.

Props​

PropTypeDefaultDescription
typeString'area'Chart type: 'area', 'line', 'bar', 'pie', 'donut', 'radialBar'
seriesArray[]Data series. Format: [{ name, data[] }] for cartesian charts; number[] for pie/donut
categoriesArray[]X-axis category labels (line, area, bar charts)
labelsArray[]Segment labels (pie, donut charts)
heightNumber | String250Chart height in pixels
widthNumber | String'100%'Chart width (defaults to full container width)
optionsObject{}Custom ApexCharts options deep-merged with Nextcloud defaults
colorsArray[]Color palette — defaults to Nextcloud CSS variable colors
toolbarBooleanfalseShow/hide the ApexCharts toolbar (zoom, download)
legendBooleantrueShow/hide the chart legend
unavailableLabelString'Chart library not available'Text shown when ApexCharts is not installed
dataSourceObjectnullOptional OpenRegister GraphQL block — see dataSource above

Slots​

SlotDescription
fallbackContent rendered when ApexCharts is not available

Reference (auto-generated)​

The tables below are generated from the SFC source via vue-docgen-cli. They reflect what's actually in CnChartWidget.vue and update automatically whenever the component changes.

Props​

NameTypeRequiredDefaultDescription
typestring'area'Chart type: area, line, bar, pie, donut, radialBar
seriesArray[]Chart data series. Format depends on chart type. For line/area/bar: [{ name: string, data: number[] }] For pie/donut: number[]
categoriesArray<string>[]X-axis categories (for line, area, bar charts)
labelsArray<string>[]Labels (for pie, donut charts)
heightunion250Chart height in pixels. Use 'auto' for container-based sizing.
widthunion'100%'Chart width. Defaults to '100%' (fills container).
optionsobject\{\}Custom ApexCharts options (deep-merged with defaults).
colorsArray<string>[]Chart color palette. Defaults to Nextcloud theme colors.
toolbarbooleanfalseShow or hide the toolbar (zoom, download, etc.)
legendbooleantrueShow or hide the legend
unavailableLabelstring() =&gt; t('nextcloud-vue', 'Chart library not available')Label shown when ApexCharts is not available
dataSourceobjectnullManifest dataSource block. When set, series / categories / labels are resolved from the GraphQL response via the dataSource selectors and override the static props of the same names. Static props remain the fallback while the query is loading or when no dataSource is configured. Supported shapes (one of): - Count shorthand: { register?, schema, filter?, aggregate: 'count' } - Bucket shorthand: { register?, schema, filter?, bucket: { field, interval, metric?, metricField?, fromVar?, toVar?, staticRange? } } — emits OR's groupBy argument. When mounted under a CnDashboardPage with dateRange.enabled, from / to come from the injected cnDashboardDateRange ref; otherwise they come from bucket.staticRange. If neither is available no query is fired and the chart shows its fallback. - Raw GraphQL: { graphql: { query, variables?, selectors } }.
widgetIdstring''Widget id used to match cn:widget:refresh event-bus events (broadcast by CnWidgetWrapper's Refresh action). When the bus fires with a matching widgetId, the chart re-queries its dataSource. Passed by CnDashboardPage from the layout item. Empty disables bus-driven refresh (the chart still refetches reactively when its dataSource / range changes).

Slots​

NameBindingsDescription
fallback—

Refresh wiring​

PropTypeDefaultDescription
widgetIdString''Matches cn:widget:refresh event-bus events (broadcast by CnWidgetWrapper's Refresh); on a matching id the chart re-queries its dataSource.