Skip to main content

CnHeaderWidget

Banner / header widget with background image, overlay, title/subtitle and CTA button.

Part of the dashboard widget library (v2). Registered with the dashboard widget registry and consumed by LaunchPad's widget grid. See the widget library overview and docs/architecture/cards-and-widgets.md.

Reference​

Props​

NameTypeRequiredDefaultDescription
contentobject\{\}Persisted widget content: {title, subtitle, backgroundImageUrl, backgroundImageFileId, backgroundColor, overlayMode, overlayColor, overlayOpacity, textColor, textAlign, verticalAlign, height, cta}. All fields are optional except title; unknown enum values collapse to documented defaults and the renderer never throws.
placementobjectnullPlacement entity — reserved to match the renderer contract.
nowDatenullThe moment the greeting and the date line are computed for. Leave empty for the current time.

Greeting and date​

Three optional content keys turn the header into a greeting. Without them the header renders as before.

KeyTypeDescription
greetingtrue | "full"The heading greets the signed-in user by time of day: "Good morning", "Good afternoon" or "Good evening", followed by the first name. "full" uses the whole display name. The greeting replaces title.
showDatebooleanAdds a line above the heading with today's date, written out in the user's locale.
plainbooleanNo coloured background, text in the normal text colour, aligned to the start. This is how a greeting usually sits on a dashboard.
{ "widgetKey": "header", "props": { "content": { "greeting": true, "showDate": true, "plain": true } } }

A view switch beside the greeting (views)​

content.views puts a CnSegmentedControl at the right of the heading: { ariaLabel?, options: [{ label, route, params? }] }. The checked option is the one whose route is current (else the first); choosing another pushes its route. Without a router nothing renders. Labels and ariaLabel go through the host translate function.

{ "widgetKey": "header", "props": { "content": { "greeting": true, "showDate": true, "plain": true,
"views": { "ariaLabel": "View", "options": [{ "label": "My work", "route": "Dashboard" }, { "label": "My team", "route": "TeamDashboard" }] } } } }

Switching the page's views (option.view)​

An option can carry view instead of route: { "label": "My team", "view": "team" }. It then selects that view of the page the widget sits on (the page's views, see CnDashboardPage) instead of navigating, and every option points aria-controls at the page's view region. An option whose view names no view of the page is left out. Route and view options can be mixed: a route option still navigates. A view option works without a router.

{ "id": "greeting", "type": "header", "content": { "greeting": true, "showDate": true, "ground": true,
"views": { "ariaLabel": "Whose work", "options": [{ "label": "My work", "view": "mine" }, { "label": "My team", "view": "team" }] } } }

On the page ground (ground)​

content.ground: true draws the greeting on the page ground instead of in a card: the plain look with no padding, the date line 6px above the heading, and the heading at 32px (--cn-header-ground-title-size). On a dashboard the widget then has no card either.

{ "type": "header", "content": { "greeting": true, "showDate": true, "ground": true,
"views": { "ariaLabel": "View", "options": [{ "label": "My work", "route": "Dashboard" }, { "label": "My team", "route": "TeamDashboard" }] } } }

A ground greeting takes its own height​

With content.ground: true the widget takes its own height instead of its grid cell's, so a content.views switch sits on the heading's line (bottom-aligned with it) however tall the cell is, and a size-to-content cell can shrink to it. A banner without ground still fills its cell.

Kicker prefix and emblem​

content.kicker (an i18n key) prefixes the date line: "Customer contact · Monday 5 October 2026". content.emblem draws an emblem beside the date line and heading, centred on them: a URL, or true for the theme's --nldesign-emblem-url. It is 52px high (--cn-header-emblem-size) with a 16px gap (--cn-header-emblem-gap), and it is decoration.