---
title: Dashboard
description: Dashboard
element: vaadin-dashboard
---

## Description

A responsive, grid-based dashboard layout component

### Quick Start

Assign an array to the [`items`](/elements/vaadin-dashboard#items) property.
Set a renderer function to the [`renderer`](/elements/vaadin-dashboard#renderer) property.

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

```html
<vaadin-dashboard></vaadin-dashboard>
```

```js
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-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](https://vaadin.com/docs/latest/styling/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:
```js
{
  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](#dashboardi18n)

### items

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

An array containing the items of the dashboard

See also: [DashboardItem](#dashboarditem), [DashboardSectionItem](#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](#dashboarditem), [DashboardRenderer](#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:** `CustomEvent`

Fired before an item is removed

### dashboard-item-move-mode-changed

**Type:** `CustomEvent`

Fired when an item move mode changed

### dashboard-item-moved

**Type:** `CustomEvent`

Fired when an item was moved

### dashboard-item-removed

**Type:** `CustomEvent`

Fired when an item was removed

### dashboard-item-resize-mode-changed

**Type:** `CustomEvent`

Fired when an item resize mode changed

### dashboard-item-resized

**Type:** `CustomEvent`

Fired when an item was resized

### dashboard-item-selected-changed

**Type:** `CustomEvent`

Fired when an item selected state changed

## Types

### DashboardI18n

```ts
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

```ts
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;
}
```

### DashboardItemModel

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

### DashboardRenderer

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

### DashboardSectionItem

```ts
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[];
}
```