CnWidgetWrapper
Container shell around a dashboard widget. Provides a header with icon and title, a scrollable content area, and an optional footer with action links. Accepts a styleConfig object for runtime style overrides (background, border, padding). Used internally by CnDashboardPage for all non-tile widgets.
Try it
Usage
<!-- Basic wrapper -->
<CnWidgetWrapper title="My Cases" icon-url="/apps/myapp/img/icon.svg">
<MyCasesChart :data="chartData" />
</CnWidgetWrapper>
<!-- Without header (borderless, flush — for self-contained card widgets) -->
<CnWidgetWrapper :show-title="false" :borderless="true">
<CnStatsBlock :stats="kpis" />
</CnWidgetWrapper>
<!-- With NC widget object (used by CnDashboardPage internally) -->
<CnWidgetWrapper
:title="widget.title"
:icon-url="widget.iconUrl"
:icon-class="widget.iconClass"
:buttons="widget.buttons">
<CnWidgetRenderer :widget="widget" />
</CnWidgetWrapper>
<!-- With custom footer and header actions -->
<CnWidgetWrapper title="Tasks">
<template #actions>
<NcButton type="tertiary" @click="refresh">Refresh</NcButton>
</template>
<TaskList :items="tasks" />
<template #footer>
<a href="/apps/tasks">View all</a>
</template>
</CnWidgetWrapper>
Props
| Prop | Type | Default | Description |
|---|---|---|---|
title | String | 'Widget' | Widget title shown in the header |
eyebrow | String | '' | A short muted line above the title ("Saldo per week" above "Prognose 13 weken"), through the host translate. On a dashboard it comes from the widget definition's eyebrow |
subtitle | String | '' | A muted line under the title ("Dit kwartaal, beslist binnen de termijn"), through the host translate. On a dashboard it comes from the widget definition's subtitle ; on a detail page the widget's subtitle may also be [{ "when": <visibleWhen>, "text": "..." }], the first entry whose condition holds for the record and its @context rows (DqZaakDocumenten: only on a case type with documentReview.enabled) |
showTitle | Boolean | true | Whether to render the header bar |
chrome | String | 'default' | Card chrome variant. 'default' uses the library card chrome; 'nc-dashboard' reproduces the native Nextcloud Dashboard panel exactly (translucent blurred background via --color-main-background-blur + --filter-background-blur, --border-radius-container-large corners, no border/shadow, 16px header with a 20px/700 title and 32px leading icon, content inset 16px). styleConfig overrides still layer on top. |
showActions | Boolean | true | Whether the header's overflow action menu (Refresh / Documentation / Request-a-feature + #action-items) renders. Set false for compact surfaces (e.g. a KPI tile) to drop the menu and free header width. |
borderless | Boolean | false | Remove border and background — makes the wrapper transparent |
flush | Boolean | false | Remove content padding — lets content extend edge-to-edge |
chromeless | Boolean | false | Draw no card at all: no border, no background, no content padding, no title row, no header divider. Use it wherever the surface around the widget already drew the card and named it, a tab panel above all. It implies borderless and flush, and it overrides showTitle, so one prop says the whole thing. Controls in the actions slot keep their header: a control is not chrome, and the Save button that commits an inline edit lives there. The wrapper element still renders, because CnObjectDataWidget measures its overflow against .cn-widget-wrapper__content and the library's table and detail-page CSS size their content areas through that node. |
iconUrl | String | null | Image URL for the header icon |
iconClass | String | null | CSS class for the header icon (e.g. Nextcloud icon class) |
titleIconPosition | String | 'right' | Position of the title-icon slot in the header: 'left' places it before the title group; 'right' places it after the actions |
titleIconColor | String | null | CSS color value applied to the title-icon slot container (e.g. '#e74c3c') |
buttons | Array | [] | Footer button links: [{ text, link }] |
styleConfig | Object | {} | Runtime style overrides: { backgroundColor?, borderStyle?, borderWidth?, borderColor?, borderRadius?, padding?: { top, right, bottom, left }, headerStyle?: { backgroundColor?, textColor? } }. The optional headerStyle colours the header bar per-widget. |
refreshing | Boolean | false | When bound (e.g. :refreshing="loading" around the host's refetch), the Refresh item is disabled and shows a loading spinner for exactly as long as this stays true — so the spinner reflects the real refresh time. |
Slots
| Slot | Description |
|---|---|
| default | Widget content rendered in the scrollable body area |
actions | Buttons or controls placed in the right side of the header |
title-icon | Extra icon element rendered in the header at the position controlled by titleIconPosition (left of title or right of actions) |
footer | Custom footer content (replaces the buttons prop rendering) |
Built-in Actions menu
CnWidgetWrapper ships with a small overflow … menu in the header — the shared CnActionsMenu — containing up to three actions. Documentation and Request-a-feature are functional without any host wiring when the wrapper is mounted under CnAppRoot; Refresh is shown only when something will handle it (see below):
- Refresh — shown only when it will do something.
showRefreshis tri-state:true/falseforce it on/off, and the default (null) is auto — the item renders only when a parent has attached an@refreshlistener. This prevents dead buttons on widgets that can't refresh (e.g. a prop-drivenCnObjectDataWidget) and on detail-page auto-body widgets where the page owns refresh. A widget that wants a manual Refresh while refreshing itself via the bus (no@refreshlistener) can set:show-refresh="true"explicitly. When shown and clicked it emits@refresh, then (unless the host listener callsevent.preventDefault()) emits on the@nextcloud/event-buschannelcn:widget:refreshwith payload{ widgetId, title }. - Documentation — rendered only when a
documentationUrlis supplied. Opens the host-provided link in a new tab (target="_blank",rel="noopener noreferrer"); no JS handler. Apps pass the URL from the widget configuration (:documentation-url="widget.documentationUrl"); customise the wording withdocumentationLabel. - Request a feature — on by default; emits
@request-feature, then (unless suppressed) opens the forge's feature-request issue form in a new tab with thewidget:<id>surface as its English headline, built from theCnAppRootinjects. The host can override the default by binding@request-featureand callingevent.preventDefault()to handle it themselves.
Force Refresh on/off per-instance with :show-refresh="true"/:show-refresh="false" (the legacy hide-refresh alias still opts out for back-compat); opt out of Request-a-feature with :show-request-feature="false" (the legacy hide-request-feature alias also still works). When everything is hidden — Refresh auto-hidden or opted out, Request-a-feature opted out, no documentationUrl, and no #action-items slot content — the overflow menu disappears entirely. To drop the entire actions area in one go — e.g. on a compact KPI tile whose only header affordance is a date chip — set :show-actions="false".
Set :widget-id so the event-bus payload + modal surface tag are stable across renames; otherwise the wrapper falls back to a slugified title.
Opting into Refresh
Because Refresh auto-hides unless a parent attaches an @refresh listener, opting in is the act of wiring one of the patterns below. A widget that refreshes itself purely via the bus (no @refresh listener — mode 3) must also pass :show-refresh="true" so the action renders.
A widget can opt in to Refresh in one of three ways. Pick whichever fits the widget's existing reactivity model — all three are first-class.
1. Ref-callable refresh() method (canonical)
The cleanest pattern: expose a method, let the host call it through the ref.
<template>
<CnWidgetWrapper title="Outgoing calls" widget-id="outgoing-calls-daily">
<CallsChart ref="chart" />
</CnWidgetWrapper>
</template>
<script>
export default {
// Inside CallsChart.vue:
methods: {
async refresh() {
this.data = await this.$store.dispatch('callLogs/refetch')
},
},
}
</script>
The host listens via the event-bus channel and routes by id (see mode 3 below for the wiring), or the wrapper invokes the method directly when integrated.
2. Reactive refreshTrigger prop
Useful when the widget cannot easily expose a ref (e.g. async-loaded). The host increments a timestamp; the widget watches it.
<template>
<CnWidgetWrapper title="Outgoing calls" widget-id="outgoing-calls-daily" :show-refresh="true">
<CallsChart :refresh-trigger="callsRefreshTrigger" />
</CnWidgetWrapper>
</template>
<script>
import { subscribe } from '@nextcloud/event-bus'
export default {
data() {
return { callsRefreshTrigger: 0 }
},
mounted() {
subscribe('cn:widget:refresh', ({ widgetId }) => {
if (widgetId === 'outgoing-calls-daily') {
this.callsRefreshTrigger = Date.now()
}
})
},
}
</script>
3. Event-bus subscription (direct)
The widget subscribes itself; no host plumbing needed.
<script>
import { subscribe, unsubscribe } from '@nextcloud/event-bus'
export default {
props: { widgetId: { type: String, required: true } },
mounted() {
this._onRefresh = ({ widgetId }) => {
if (widgetId === this.widgetId) this.refetch()
}
subscribe('cn:widget:refresh', this._onRefresh)
},
beforeDestroy() {
unsubscribe('cn:widget:refresh', this._onRefresh)
},
methods: {
async refetch() { /* ... */ },
},
}
</script>
Reference (auto-generated)
The tables below are generated from the SFC source via vue-docgen-cli. They reflect what's actually in CnWidgetWrapper.vue and update automatically whenever the component changes.
OpenRegister reliance
medium: this component relies on OpenRegister for part of what it does. 0 direct references, 4 files reached through imports.
Through: CnActionsMenu.
See the reliance overview for the filterable list.
Props
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
title | string | () => t('nextcloud-vue', 'Widget') | Widget title | |
eyebrow | string | '' | A short muted line above the title ("Saldo per week" above "Prognose 13 weken"), through the host translate. Empty draws none. | |
subtitle | string | '' | A muted line under the title, such as the period a chart covers. Run through the host translate function. Empty draws none. | |
showTitle | boolean | true | Whether to show the header with title | |
chrome | string | 'default' | Chrome variant for the wrapper card. - 'default' — the library's own card chrome (opaque background, 1px border, compact header). - 'nc-dashboard' — matches the native Nextcloud Dashboard panel exactly using the same design tokens: translucent blurred background (--color-main-background-blur + --filter-background-blur), --border-radius-container-large corners, no border/shadow, a 16px header with a 20px/700 title and 32px leading icon, and content inset 16px on the sides + bottom. styleConfig overrides still layer on top so a user can customise any token. | |
borderless | boolean | false | Remove border and background — makes the wrapper transparent. Useful for widgets that are self-contained cards (e.g. CnStatsBlock). | |
flush | boolean | false | Remove content padding — allows content to go edge-to-edge. Useful for list-style widgets where items should span the full width. | |
chromeless | boolean | false | Draw NO card of this widget's own: no border, no background, no content padding, no title row and no header divider. For a surface that already supplies the card and the heading — a tab panel being the case that matters, where a nested card repeats both. The wrapper ELEMENT still renders. That is the contract, not an oversight: CnObjectDataWidget measures its overflow against .cn-widget-wrapper__content (closest() plus a ResizeObserver on that node), src/css/table.css gives a table inside it its edge-to-edge treatment, and src/css/detail-page.css and dashboard.css size their content areas through it. Dropping the node would take all of that out silently — closest() returning null reads as "nothing overflows", never as an error. Controls in the actions slot are NOT chrome and keep their header: the Save button that commits an inline edit lives there, and a panel that hides it is silently unsaveable. chromeless is what an integration provider already asks for through CnDetailWidgetHost (bareWidget), so this is the same word for the same thing on every path into the wrapper. | |
iconUrl | string | null | Icon URL (image) | |
iconClass | string | null | Icon CSS class (e.g., Nextcloud icon class) | |
titleIconPosition | string | 'right' | Position of the title-icon slot in the header. 'left' places it before the title; 'right' places it after the actions. | |
titleIconColor | string | null | Explicit CSS colour for the header icon. Overrides titleIconVariant. Must be a CSS custom property or a theme token — never a literal hex (NL Design System: the nldesign app re-themes by overriding the Nextcloud variables, and a hardcoded colour ignores that). | |
titleIconVariant | string | 'primary' | Semantic colour for the header icon. Every widget's icon is coloured — primary (the theme colour) is the default, and a widget whose subject already carries a semantic meaning names it here so the icon says so at a glance (a Depublished list is error, a Concepts list warning, a Published list success). | |
buttons | array | [] | Footer action buttons: [{ text, link }] | |
titleTone | string | '' | The title's tone: side titles the card as a side card in the board look (a 15px muted heading), for a card in a page's right column. Manifest: titleTone on the widget definition. | |
headerActions | array | [] | Resolved header buttons, [{ key, label, icon, variant, run }], from a host that draws several cards and cannot provide them per card (CnDashboardPage). A detail host's provided list wins. | |
headerLink | {label: string, route?: string, params?: object, query?: object, href?: string}|null | null | One text link in the header's actions group, before the overflow menu: { label, route?, params?, query?, href? }. A route is a named router link (needs a router), an href a plain anchor. The label goes through the host translate function. Null (the default) draws nothing. Manifest: headerLink on the widget definition or its layout entry. | |
showActions | boolean | true | Whether the header's overflow action menu (Refresh / Documentation / Request-a-feature + any #action-items) renders. Shown by default; set false for compact surfaces — e.g. a KPI tile whose only header affordance is a date chip — to drop the menu and free header width. | |
styleConfig | { backgroundColor: string, borderStyle: string, borderWidth: number, borderColor: string, borderRadius: number, padding: { top: number, right: number, bottom: number, left: number } } | \{\} | Style configuration for the wrapper. | |
hideRefresh | boolean | false | Hide the built-in Refresh item from the overflow action menu. The Refresh item is shown by default — set this when the widget has no refreshable data source (e.g. a static tile). Alias for the inverse :show-refresh="false"; either form opts out. | |
hideRequestFeature | boolean | false | Hide the built-in Request-a-feature item from the overflow action menu. Shown by default; set when the consuming app has no public issue tracker to link out to. Alias for the inverse :show-request-feature="false"; either form opts out. | |
showRefresh | union | null | Whether to show the built-in Refresh item. Tri-state: - true / false — force the action on or off. - null (the default) — auto: show the action only when a parent has attached an @refresh listener (i.e. something will actually handle the refresh). This keeps widgets that can't refresh — e.g. a prop-driven CnObjectDataWidget — from showing a dead button. Widgets that refresh themselves via the cn:widget:refresh event bus (with no @refresh listener) should set :show-refresh="true" explicitly. hideRefresh (or :show-refresh="false") always wins. | |
showRequestFeature | boolean | true | Inverse of hideRequestFeature. Defaults to true so the action renders. Set :show-request-feature="false" to hide it. Either flag hides the action. | |
showReportBug | boolean | true | Whether the built-in "Report a bug" item renders. On by default — the trio Request a feature / Report a bug / Documentation is the contract for every widget; this exists for the rare surface that must suppress one deliberately. | |
showDocumentation | boolean | true | Whether the built-in "Documentation" item renders. On by default, for the same reason as showReportBug. The item's target is resolved by the shared menu (see docsAnchor), so leaving it on costs the host nothing. | |
documentationUrl | string | '' | Explicit documentation link for this widget, opened in a new tab. Usually unnecessary: leave it empty and set docsAnchor instead, so the link is built from the app-wide documentation base and lands on this widget's own section. | |
documentationLabel | string | () => t('nextcloud-vue', 'Documentation') | Optional pre-translated label for the Documentation action. Defaults to the lib's translation of "Documentation". | |
widgetId | string | '' | Widget id for the built-in default Refresh / Request-a-feature handlers (B2). Forwarded as the surface: "widget:<id>" value on the Actions menu (the English headline fallback for its forge deep-links) AND as the widgetId field on the cn:widget:refresh event-bus payload. When unset, the wrapper falls back to a slugified displayTitle, which works but is less stable than an explicit id. | |
docsAnchor | string | '' | This widget's own section in the app's documentation, appended to the app-wide documentation base URL (provided by CnAppRoot) to build the Actions menu's Documentation deep-link. A bare slug becomes a #fragment. Supply it per widget type — without it the item still renders, but lands on the docs homepage rather than this widget. | |
reportBugUrl | string | '' | Explicit "Report a bug" target for the Actions menu. Empty (the default) builds a new-issue deep-link on the app's own forge. | |
highContrast | boolean | false | Declares that this widget wants a high contrast treatment. The flag reaches the theme as data-cn-high-contrast and a --high-contrast class; the component picks no colour of its own (ADR-003). A theme that says nothing about the flag renders the widget unchanged. | |
specRef | string | '' | Optional specRef slug, forwarded to the Actions menu. Accepted for backward compatibility with the removed in-product suggestion modal; the forge issue form asks for its own context. | |
refreshing | boolean | false | Whether a refresh is currently in flight. When bound by the host (e.g. :refreshing="loading" around its refetch), the Refresh item is disabled and shows a loading spinner for exactly as long as this stays true — so the spinner reflects the real refresh time. | |
refreshLabel | string | () => t('nextcloud-vue', 'Refresh') | Optional pre-translated label for the Refresh action. Defaults to the lib's translation of "Refresh" so callers usually don't need to set this. | |
requestFeatureLabel | string | () => t('nextcloud-vue', 'Request a feature') | Optional pre-translated label for the Request-a-feature action. Defaults to the lib's translation of "Request a feature". | |
actionsMenuLabel | string | () => t('nextcloud-vue', 'Actions') | Pre-translated aria-label / tooltip for the overflow menu trigger. Defaults to "Actions". | |
translate | ((key: string) => string)|null | null | Translate function. Falls back to the injected cnTranslate, which itself defaults to an identity function. |
Events
| Name | Payload | Description |
|---|---|---|
refresh | undefined | User clicked the Refresh item in the overflow action menu. Payload: { widgetId, title }. Handlers may call the second arg's preventDefault() to suppress the built-in default (event-bus emit on cn:widget:refresh). |
request-feature | undefined | User clicked the Request a feature item. Payload: { widgetId, title }. Handlers may call the second arg's preventDefault() to suppress the built-in default (opening the forge's feature-request issue form). |
Slots
| Name | Bindings | Description |
|---|---|---|
title-icon | — | |
title-meta | — | |
actions | — | actions Custom action buttons rendered before the |
action-items | — | |
default | — | |
footer | — |
Additional props & slots
| Prop | Type | Default | Description |
|---|---|---|---|
specRef | String | '' | Accepted for backward compatibility with the removed in-product suggestion modal; no longer forwarded. |
documentationUrl | String | '' | When set, renders a Documentation item in the overflow menu that opens this link in a new tab. Empty hides it. |
documentationLabel | String | t('Documentation') | Pre-translated label for the Documentation action. |
refreshLabel | String | t('Refresh') | Pre-translated label for the Refresh action. |
requestFeatureLabel | String | t('Request a feature') | Pre-translated label for the Request-a-feature action. |
actionsMenuLabel | String | t('Actions') | Pre-translated aria-label / tooltip for the overflow … menu trigger. |
| Slot | Description |
|---|---|
title-meta | Inline content rendered next to the title (e.g. the dashboard date-range chip). |
Coloured header icon
Every widget's header icon is coloured — titleIconVariant defaults to primary, so no configuration is needed. A widget whose subject already carries a meaning names it instead: a Concepts list is warning, a Published list success, a Depublished list error. titleIconColor overrides the variant with an explicit CSS variable (never a literal hex — that would ignore the nldesign app's re-theming).
The colour is published once as --cn-widget-icon-color on the header and cascades to every icon under it.
Actions menu props
| Prop | Type | Default | Description |
|---|---|---|---|
docsAnchor | String | '' | This widget's own section in the app's documentation, appended to the app-wide base so the Documentation entry deep-links to this widget rather than the docs homepage. Prefer it over documentationUrl. |
showDocumentation | Boolean | true | Whether the Documentation entry renders. |
showReportBug | Boolean | true | Whether the Report-a-bug entry renders. |
reportBugUrl | String | '' | Explicit bug-report target; empty builds a new-issue deep-link on the app's own forge. |
titleIconVariant | String | 'primary' | Semantic header-icon colour (primary/success/warning/error/info/neutral). |
Request a feature / Report a bug / Documentation render on every widget.
High contrast
highContrast (Boolean, default false) declares that this widget wants a high contrast treatment. The flag reaches the theme as data-cn-high-contrast="true" and a cn-widget-wrapper--high-contrast class.
The component picks no colour of its own (ADR-003). A theme that says nothing about the flag renders the widget unchanged, which is what makes the flag safe to declare on any widget.
/* In the theme, not in the component. */
[data-cn-high-contrast='true'] {
--color-border: var(--color-main-text);
}
A side-card title (titleTone)
| Prop | Type | Default | Description |
|---|---|---|---|
titleTone | String | '' | side titles the card as a side card in the board look: 15px, weight 600, muted. For a card in a page's right column (DqDagAfsluiten "Uw dag"). In a manifest: titleTone: "side" on the widget definition; CnDashboardPage and CnDetailWidgetHost pass it on. |
A text link in the header (headerLink)
| Prop | Type | Default | Description |
|---|---|---|---|
headerLink | Object | null | null | One text link in the header's actions group, before the overflow menu: { label, tab?, route?, params?, query?, href? }. A tab opens that tab of the same page (a #<tab> anchor the tab strip follows), a route is a named router link (needs a router), an href a plain anchor. The label goes through the host translate function. With placement: "title" the link sits under the title instead, at the title's edge (DqDashboard "Alles bekijken"). In a manifest: headerLink on the widget definition or its layout entry. |
{ "id": "week", "type": "custom", "title": "Deadlines this week", "headerLink": { "label": "All deadlines", "route": "Cases", "query": { "due": "7d" } } }
A link to another tab of the same detail page (DqZaaktype: the side Historie card opens the Historie tab):
{ "id": "history-side", "type": "audit-trail", "headerLink": { "label": "All history", "tab": "history" } }
Theme hooks: --cn-widget-header-link-size (14px), --cn-widget-header-link-weight (600).
Buttons in the header (headerActions)
A widget definition on a detail page can declare buttons for its card's title row, the board's per-card actions ("Flow uitvoeren", "Notitie toevoegen", "Bewerken"):
{
"id": "case-flow-runs",
"type": "flow-runs",
"title": "Flows",
"headerActions": [
{ "label": "Run flow", "icon": "Play", "action": { "type": "open-modal", "target": "CnActionDialog", "props": { "objectId": "@objectId" } } },
{ "label": "Edit", "variant": "primary", "visibleWhen": { "field": "status", "op": "neq", "value": "closed" }, "action": { "type": "navigate", "route": "CaseEdit", "params": { "id": "@objectId" } } }
]
}
| Key | Description |
|---|---|
label | The button text, an i18n key. Required. |
icon | A CnIcon name. |
variant | secondary (default, outlined) or primary. |
visibleWhen | A condition on the record. One the page cannot decide (it names an endpoint or a source) hides the button. |
action | Any action the page's dispatcher takes (navigate, open-modal, api-call, a registered handler). @objectId and @object.<field> are resolved first. Required. |
Two actions belong to the detail page itself rather than to the dispatcher:
{ "type": "edit-record" }opens the page's own record edit form, the one its Edit button opens (DqZaaktype "Termijnen" Bewerken). The button is left out where the page offers no Edit.{ "type": "open-tab", "tab": "<tab id>" }opens that tab of the page, through the same#<tab>anchor aheaderLinkwithtabuses (DqZaaktypeOverzicht "Statussen" Bewerken opens the Statuses tab).
On a dashboard (CnDashboardPage) the same headerActions on a widget definition are drawn in that widget's card; the page resolves them and hands them to the card's headerActions prop. CnDetailWidgetHost resolves them and provides them to the card it puts the widget in. The outermost CnWidgetWrapper or CnDetailCard below it draws them, before its actions slot; a card inside that one does not draw them again. A title-less card gets a header for them. In a tab panel (bare), CnTabsWidget draws them in the panel's heading, or on a row of their own when the panel has no heading.