| title | Dashboard | ||
|---|---|---|---|
| description | A component for building static dashboard layouts and dynamic, user-configurable dashboards. | ||
| page-links | |||
| section-nav | commercial |
A component for building static dashboard layouts and dynamic, user-configurable dashboards.
- Static & Dynamic Dashboards
-
Static: You define a dashboard and its widgets declaratively or imperatively. The React and Web Components for this are
<DashboardLayout>&<DashboardWidget>and<vaadin-dashboard-layout>&<vaadin-dashboard-widget>respectively.Dynamic: You define the data and Dashboard generates widgets using a renderer. Dynamic dashboards support edit mode that allows the end user to move, resize, and remove widgets. The React and Web Components for this are
<Dashboard>and<vaadin-dashboard>, respectively.In Flow, the
DashboardandDashboardWidgetclasses are used for both approaches. - Widgets, Columns & Rows
-
Widgets are placed in columns and rows automatically, in the order supplied, based on the dashboard’s width and the column configuration. As the dashboard’s width changes, the number of columns is automatically adjusted based on their configured minimum and maximum width, and the widget positions are adjusted so.
You can’t place a widget in a specific column or row.
- Scrolling
-
Dashboard scrolls vertically if the contents overflow its defined height. Individual widgets don’t scroll (see Widget Content Sizing).
The following configuration options are available for the Dashboard component.
Column width can vary between a minimum and maximum size. The default maximum width is 1fr, which allows the columns to expand to fill any available space. If a fixed length value is provided, empty space is reserved at the end of rows once the columns reach their maximum width.
By default there is no limit on the number of columns, but one can be provided if needed.
The height of each dashboard row is determined by the tallest widget in that row, whose height in turn is determined by its contents. A minimum row height determines the height of empty rows, such as when a widget’s row span is stretched into an unoccupied row. The minimum height can be configured.
The horizontal and vertical spacing between widgets, and the padding along the dashboard’s edges, can be configured.
This mode uses the dense packing algorithm in the CSS grid layout model. It attempts to fill in empty slots in the layout by placing smaller widgets in them. This can affect the order of the widgets. It should be used with caution in user-configurable dashboards, as the automatic reordering of widgets may be confusing during editing.
link:{root}/frontend/demo/component/dashboard/dashboard-dense-layout.ts[role=include]Widgets consist of a content area and a header containing the widget’s title and a slot for more elements.
You can set the column span and row span to make a widget take up more than one column or row in the dashboard’s layout. The actual number of columns a widget spans is limited by the current number of columns in the dashboard, however.
The height of a widget’s contents define its default height. The height can grow because of row span or other taller widgets on the same dashboard row. If the height of the widget is constrained (e.g., by an explicitly set height), the contents of the card can overflow. You may need to incorporate a scrollable area (e.g., with Scroller) to accommodate a height smaller than the contents you place in a widget.
The width of a widget is determined by the current column width and the widget’s column span.
Contents that should cover the entire widget area should therefore be configured with 100% width and height, as well as a minimum height corresponding to its desired default height.
Static dashboards are populated declaratively (in React and Lit) / imperatively (in Flow), like normal layouts. They are a good choice for hard-coded dashboards.
Flow |
|
React |
|
Lit Web Component |
|
Dynamic dashboards offer end users the possibility to edit the layout. Dynamic dashboards are populated through a data-binding API coupled with a widget renderer function. This makes the layout configuration easy to persist and load from storage, such as a database.
Flow |
|
React |
|
Lit Web Component |
|
You can make dynamic dashboards editable by turning on editing mode, as seen in the sample above.
|
Note
|
Editing mode should be temporary.
The end user turns on editing mode when they want to edit the dashboard’s contents and turns it off when they finish editing. When turned off, you typically want to persist the dashboard configuration to a storage. While in editing mode, the widget contents are visible but not interactable.
|
The following operations are available in editing mode.
In editing mode, widgets can be selected by keyboard by moving focus to the desired widget using the kbd:[Tab] key and pressing kbd:[Space] or kbd:[Enter]. Once selected, arrow keys can be used to move and resize widgets, and to engage the accessible move and resize modes.
Widget selection is not required for editing by pointer device.
In editing mode, widgets can be moved around by:
-
drag & drop;
-
arrow keys, once the widget has been selected;
-
an accessible move-mode engaged by clicking the drag-handle in the widget’s top left corner. Move-mode is disengaged by clicking the apply-button in the widget’s center, or by pressing kbd:[Esc].
Widgets can only be moved backwards and forwards. Moving a widget past the start or end of a row moves it to the preceding or following row.
In editing mode, widgets can be resized by increasing and decreasing their column span and row span by:
-
dragging from the drag-handle in the widget’s bottom right corner;
-
kbd:[Shift] + arrow keys, once the widget has been selected;
-
an accessible resize-mode engaged by clicking the resize-handle. Resize-mode is disengaged by clicking the apply-button in the widget’s center, or by pressing kbd:[Esc].
In editing mode, widgets can be removed by clicking the Remove button in the widget’s top right corner.
Dashboard has no built-in mechanism for adding new widgets. You can implement this using an external widget selector, such as a Select drop-down, that adds the corresponding item to the dashboard.
Although widget selection is announced via a widget’s title, and the various buttons all have accessible names, the component doesn’t announce changes to a widget’s position and size out of the box. These can be provided by listening to related events emitted by the component and updating custom live regions with appropriate announcements.
link:{root}/frontend/themes/docs/screen-reader-only.css[role=include]Dynamic dashboards, with their user-editable capabilities, often require the ability to persist and load customized widget configurations to and from storage, such as a database.
The most straightforward way to persist widget configurations is by defining a custom widget/item type. This type can include custom metadata relevant to the widget content, in addition to the built-in widget/item properties.
Once you’ve defined your custom type, you can establish a mapping between your data model and the widget configuration. This involves:
-
Loading: When loading the persisted configuration, map the data from your storage to individual widget/item instances of your custom type. Each record corresponds to a single widget on the dashboard.
-
Saving: When saving the user’s customized dashboard layout, map the current configuration (e.g., column span, row span, type, custom metadata) of your dashboard’s widgets back to your data model format.
This approach allows for flexible persistence of dashboard configurations, enabling users to save and load their customized layouts across sessions.
For a simple example of how to implement this persistence approach, see the Dynamic, Editable Dashboards section above. While the example doesn’t explicitly show how to persist the data, it illustrates the concept of defining a custom type for the dashboard widgets. The specific implementation details depend on your chosen storage mechanism and data model.
Complex dashboards can benefit from being divided into titled sections. Dashboard sections always span the full width of the dashboard, and follow the same column and row configuration as the dashboard itself. They support the same moving and removal operations in editing mode as widgets.
Dashboard widgets have an ARIA role of article.
Widget and section titles are rendered as headings. Root-level widgets and sections default to heading level 2 (corresponding to an <h2> element), while widgets within sections use one level below that of the section. The root heading level can be customized to match the dashboard’s correct placement in the heading hierarchy:
dashboard.setRootHeadingLevel(3);<Dashboard rootHeadingLevel={3}><vaadin-dashboard root-heading-level="3">The following texts in the dashboard can be localized through the internationalization object:
| Property | Description |
|---|---|
|
Widget selection trigger. |
|
Widget deselection trigger. |
|
Section selection trigger. |
|
Section deselection trigger. |
|
Button that engages move-mode. |
|
Move forward button in move-mode. |
|
Move backward button in move-mode. |
|
Button that disengages move-mode. |
|
Button that engages resize-mode. |
|
Grow width button in resize-mode. |
|
Shrink width button in resize-mode. |
|
Grow height button in resize-mode. |
|
Shrink height button in resize-mode. |
|
Button that disengages resize-mode. |
|
Remove button. |
Component |
Usage Recommendations |
Generic card component that can be used in any layout |
d59db2ee-c3dd-446d-bd0d-40224b1f141e