Dashboard

Description #

A responsive, grid-based dashboard layout component

Quick Start #

Assign an array to the items property. Set a renderer function to the renderer property.

The widgets and the sections will be generated and configured based on the renderer and the items provided.

<vaadin-dashboard></vaadin-dashboard>

const dashboard = document.querySelector('vaadin-dashboard');

dashboard.items = [
  { title: 'Widget 1 title', content: 'Text 1', rowspan: 2 },
  { title: 'Widget 2 title', content: 'Text 2', colspan: 2 },
  {
    title: 'Section title',
    items: [{ title: 'Widget in section title', content: 'Text 3' }]
  },
  // ... more items
];

dashboard.renderer = (root, _dashboard, { item }) => {
  const widget = root.firstElementChild || document.createElement('vaadin-dashboard-widget');
  if (!root.contains(widget)) {
    root.appendChild(widget);
  }
  widget.widgetTitle = item.title;
  widget.textContent = item.content;
};

Styling #

The following custom properties are available:

Custom Property	Description
--vaadin-dashboard-col-min-width	minimum column width of the dashboard
--vaadin-dashboard-col-max-width	maximum column width of the dashboard
--vaadin-dashboard-row-min-height	minimum row height of the dashboard
--vaadin-dashboard-row-height	fixed row height of the dashboard. Must be in length units. Overrides --vaadin-dashboard-row-min-height and prevents rows from growing to fit content
--vaadin-dashboard-col-max-count	maximum column count of the dashboard
--vaadin-dashboard-gap	gap between child elements. Must be in length units (0 is not allowed, 0px is)
--vaadin-dashboard-padding	space around the dashboard's outer edges. Must be in length units (0 is not allowed, 0px is)

The following state attributes are available for styling:

Attribute	Description
editable	Set when the dashboard is editable.
dense-layout	Set when the dashboard is in dense mode.
item-selected	Set when an item is selected.

See Styling Components documentation.

Properties #

denseLayout #

Type: boolean

Whether the dashboard layout is dense.

editable #

Type: boolean

Whether the dashboard is editable.

i18n #

Type: DashboardI18n

The object used to localize this component. To change the default localization, replace this with an object that provides all properties, or just the individual properties you want to change.

The object has the following structure and default values:

{
  selectSection: 'Select section for editing',
  selectWidget: 'Select widget for editing',
  remove: 'Remove',
  resize: 'Resize',
  resizeApply: 'Apply',
  resizeShrinkWidth: 'Shrink width',
  resizeGrowWidth: 'Grow width',
  resizeShrinkHeight: 'Shrink height',
  resizeGrowHeight: 'Grow height',
  move: 'Move',
  moveApply: 'Apply',
  moveForward: 'Move Forward',
  moveBackward: 'Move Backward',
}

See also: DashboardI18n

items #

Type: (DashboardItem | DashboardSectionItem<DashboardItem>)[]

An array containing the items of the dashboard

See also: DashboardItem, DashboardSectionItem

renderer #

Type: DashboardRenderer<DashboardItem> | null | undefined

Custom function for rendering a widget for each dashboard item. Placing something else than a widget in the wrapper is not supported. Receives three arguments:

• root The container for the widget.
• dashboard The reference to the <vaadin-dashboard> element.
• model The object with the properties related with the rendered item, contains:
  • model.item The item.

See also: DashboardItem, DashboardRenderer

rootHeadingLevel #

Type: number | null | undefined

Root heading level for sections and widgets. Defaults to 2.

If changed to e.g. 1:

• sections will have the attribute aria-level with value 1
• non-nested widgets will have the attribute aria-level with value 1
• nested widgets will have the attribute aria-level with value 2

Events #

dashboard-item-before-remove #

Type: DashboardItemBeforeRemoveEvent

Fired before an item is removed. Calling preventDefault() on the event will cancel the removal.

dashboard-item-move-mode-changed #

Type: DashboardItemMoveModeChangedEvent

Fired when an item move mode changed

dashboard-item-moved #

Type: DashboardItemMovedEvent

Fired when an item was moved

dashboard-item-removed #

Type: DashboardItemRemovedEvent

Fired when an item was removed

dashboard-item-resize-mode-changed #

Type: DashboardItemResizeModeChangedEvent

Fired when an item resize mode changed

dashboard-item-resized #

Type: DashboardItemResizedEvent

Fired when an item was resized

dashboard-item-selected-changed #

Type: DashboardItemSelectedChangedEvent

Fired when an item selected state changed

Types #

DashboardI18n #

export interface DashboardI18n {
  selectWidget?: string;
  selectSection?: string;
  remove?: string;
  resize?: string;
  resizeApply?: string;
  resizeShrinkWidth?: string;
  resizeGrowWidth?: string;
  resizeShrinkHeight?: string;
  resizeGrowHeight?: string;
  move?: string;
  moveApply?: string;
  moveForward?: string;
  moveBackward?: string;
}

DashboardItem #

export interface DashboardItem {
  /**
   * The id of the item.
   * The identifier should be unique among the dashboard items.
   * If a unique identifier is not provided, reassigning new item instances
   * to the dashboard while a widget is focused may cause the focus to be lost.
   */
  id?: unknown;

  /**
   * The column span of the item
   */
  colspan?: number;

  /**
   * The row span of the item
   */
  rowspan?: number;
}

DashboardItemBeforeRemoveEvent #

/**
 * Fired before an item is removed. Calling preventDefault() on the event will cancel the removal.
 */
export type DashboardItemBeforeRemoveEvent<TItem extends DashboardItem> = CustomEvent<{
  item: TItem | DashboardSectionItem<TItem>;

  items: Array<TItem | DashboardSectionItem<TItem>>;

  section: DashboardSectionItem<TItem> | undefined;
}>;

DashboardItemModel #

export interface DashboardItemModel<TItem> {
  item: TItem;
}

DashboardItemMovedEvent #

/**
 * Fired when an item was moved
 */
export type DashboardItemMovedEvent<TItem extends DashboardItem> = CustomEvent<{
  item: TItem | DashboardSectionItem<TItem>;

  items: Array<TItem | DashboardSectionItem<TItem>>;

  section: DashboardSectionItem<TItem> | undefined;
}>;

DashboardItemMoveModeChangedEvent #

/**
 * Fired when an item move mode changed
 */
export type DashboardItemMoveModeChangedEvent<TItem extends DashboardItem> = CustomEvent<{
  item: TItem | DashboardSectionItem<TItem>;
  value: boolean;
}>;

DashboardItemRemovedEvent #

/**
 * Fired when an item was removed
 */
export type DashboardItemRemovedEvent<TItem extends DashboardItem> = CustomEvent<{
  item: TItem | DashboardSectionItem<TItem>;

  items: Array<TItem | DashboardSectionItem<TItem>>;

  section: DashboardSectionItem<TItem> | undefined;
}>;

DashboardItemResizedEvent #

/**
 * Fired when an item was resized
 */
export type DashboardItemResizedEvent<TItem extends DashboardItem> = CustomEvent<{
  item: TItem;

  items: Array<TItem | DashboardSectionItem<TItem>>;
}>;

DashboardItemResizeModeChangedEvent #

/**
 * Fired when an item resize mode changed
 */
export type DashboardItemResizeModeChangedEvent<TItem extends DashboardItem> = CustomEvent<{
  item: TItem;
  value: boolean;
}>;

DashboardItemSelectedChangedEvent #

/**
 * Fired when an item selected state changed
 */
export type DashboardItemSelectedChangedEvent<TItem extends DashboardItem> = CustomEvent<{
  item: TItem | DashboardSectionItem<TItem>;
  value: boolean;
}>;

DashboardRenderer #

export type DashboardRenderer<TItem extends DashboardItem> = (
  root: HTMLElement,
  owner: Dashboard<TItem>,
  model: DashboardItemModel<TItem>,
) => void;

DashboardSectionItem #

export interface DashboardSectionItem<TItem extends DashboardItem> {
  /**
   * The id of the item.
   * The identifier should be unique among the dashboard items.
   * If a unique identifier is not provided, reassigning new item instances
   * to the dashboard while a widget is focused may cause the focus to be lost.
   */
  id?: unknown;

  /**
   * The title of the section
   */
  title?: string;

  /**
   * The items of the section
   */
  items: TItem[];
}