Dashboard Widget Component

Introduction

The Dashboard Widget Component is a specialized container designed exclusively for use within the Dashboard Component. It defines a widget's position and size within the dashboard grid system and wraps the actual content components. Each dashboard-widget occupies a specific area of the dashboard grid and can be resized and repositioned when the dashboard is in edit mode.

YAML Structure

Dashboard widgets must be direct children of a dashboard component and contain the actual components to display.

Basic Structure

component: dashboard-widget
name: widgetName
props:
  options: {} # Grid positioning and display settings
children: [] # Components to render inside the widget

Attribute Description

Main Properties

Property	Type	Description	Required
name	string	Unique identifier for the widget within the dashboard	Yes
props.options	object	Widget configuration including grid positioning	Yes
children	array	Components to render inside the widget	Yes

Options Object

Required Grid Positioning

Property	Type	Description	Required
row	number	Starting row position in the grid (1-based)	Yes
col	number	Starting column position in the grid (1-based)	Yes
rowSpan	number	Number of rows the widget spans	Yes
colSpan	number	Number of columns the widget spans	Yes

Optional Display Settings

Property	Type	Description	Default
title	string	Widget title displayed in header	-
showHeader	boolean	Show/hide widget header	true
className	string	CSS class for custom styling	-
minRowSpan	number	Minimum rows when resizing	1
maxRowSpan	number	Maximum rows when resizing	dashboard rows
minColSpan	number	Minimum columns when resizing	1
maxColSpan	number	Maximum columns when resizing	dashboard columns

Examples

Basic Widget with DataGrid

component: dashboard-widget
name: ordersWidget
props:
  options:
    row: 1
    col: 1
    rowSpan: 6
    colSpan: 8
    title: Order Management
    showHeader: true
children:
  - component: datagrid
    props:
      query: orders
      enableSort: true
      enableFilter: true
      columns:
        - name: orderNumber
          label: Order #
        - name: customerName
          label: Customer
        - name: orderDate
          label: Date
        - name: status
          label: Status
        - name: totalAmount
          label: Amount

Widget with Summary Component

component: dashboard-widget
name: metricsWidget
props:
  options:
    row: 1
    col: 9
    rowSpan: 3
    colSpan: 4
    title: Key Metrics
    showHeader: true
    className: metrics-card
children:
  - component: summary
    props:
      items:
        - label: Total Sales
          value: "{{ format query.totalSales '$0,0.00' }}"
          icon: trending-up
          color: success
        - label: Active Orders
          value: "{{ query.activeOrders }}"
          icon: package
          color: info
        - label: Pending Shipments
          value: "{{ query.pendingShipments }}"
          icon: truck
          color: warning

Widget with Nested Layout

component: dashboard-widget
name: complexWidget
props:
  options:
    row: 4
    col: 1
    rowSpan: 8
    colSpan: 12
    title: Analytics Dashboard
    showHeader: true
    minRowSpan: 4
    maxRowSpan: 12
    minColSpan: 6
    maxColSpan: 12
children:
  - component: layout
    props:
      orientation: horizontal
      cols: 2
    children:
      - component: chart
        props:
          type: bar
          title: Monthly Revenue
          dataSource:
            query: monthlyRevenue
            filters:
              year: "{{ dashboard.year }}"
      - component: chart
        props:
          type: pie
          title: Revenue by Category
          dataSource:
            query: revenueByCategory
            filters:
              dateRange: "{{ dashboard.dateRange }}"

Widget Without Header

component: dashboard-widget
name: contentWidget
props:
  options:
    row: 1
    col: 1
    rowSpan: 4
    colSpan: 4
    showHeader: false
children:
  - component: calendar
    props:
      view: month
      events:
        query: events
        filter:
          userId: "{{ dashboard.userId }}"

Widget with Size Constraints

component: dashboard-widget
name: constrainedWidget
props:
  options:
    row: 5
    col: 5
    rowSpan: 4
    colSpan: 4
    title: Notifications
    minRowSpan: 3 # Cannot be resized smaller than 3 rows
    maxRowSpan: 6 # Cannot be resized larger than 6 rows
    minColSpan: 3 # Cannot be resized smaller than 3 columns
    maxColSpan: 8 # Cannot be resized larger than 8 columns
children:
  - component: collection
    props:
      dataSource:
        query: notifications
        limit: 10
      template:
        component: card
        props:
          title: "{{ item.title }}"
          description: "{{ item.message }}"
          timestamp: "{{ item.createdAt }}"

Data Access

Dashboard widgets automatically have access to all toolbar input values from their parent dashboard through the dashboard context:

# Within any component inside a dashboard-widget:
props:
  filters:
    dateRange: "{{ dashboard.dateRange }}"
    customer: "{{ dashboard.customer }}"
    warehouse: "{{ dashboard.warehouse }}"

This allows widgets to react dynamically to toolbar input changes without additional configuration.

Edit Mode Behavior

When the parent dashboard has edit mode enabled and active:

Resize Features

• Resize Handles: Appear on widget borders
• Grid Snapping: Widget snaps to grid cells during resize
• Persisted Final Size: The released mouse position is committed, so saved layouts preserve the final resized span
• Size Constraints: Respects min/max span settings
• Visual Feedback: Shows grid overlay during resize

Reposition Features

• Drag Handle: Appears in widget header (if showHeader is true)
• Drag and Drop: Move widget to new grid position
• Persisted Final Position: The released mouse position is committed, so saved layouts preserve the final row/column
• Collision Detection: Prevents overlapping with other widgets
• Grid Alignment: Automatically aligns to grid cells

Remove Features

• Delete Button: Appears in widget header
• Confirmation: May prompt for confirmation before removal
• Undo Support: Removed widgets can be restored if undo is implemented

Best Practices

Grid Positioning

1. Start Position: Begin widgets at row 1, col 1 and work outward
2. Avoid Overlaps: Ensure widget positions don't overlap
3. Leave Space: Consider leaving space for future widgets
4. Alignment: Align related widgets in rows or columns

Widget Sizing

1. Content Appropriate: Size widgets based on their content needs
2. Importance: Larger spans for more important information
3. Aspect Ratio: Consider natural aspect ratios for charts and images
4. Minimum Sizes: Set realistic minimums for usability

Performance

1. Component Choice: Use lightweight components for frequently updated widgets
2. Data Queries: Optimize queries to avoid unnecessary data fetching
3. Lazy Loading: Consider loading widget content on demand
4. Update Frequency: Balance real-time updates with performance

User Experience

1. Clear Titles: Use descriptive titles for widget identification
2. Consistent Headers: Show headers consistently across widgets
3. Logical Grouping: Position related widgets near each other
4. Resize Constraints: Set sensible min/max values for better UX

Common Patterns

Metrics Row

# Three equal-width metric widgets across the top
- component: dashboard-widget
  props:
    options:
      row: 1
      col: 1
      rowSpan: 2
      colSpan: 4
      title: Metric 1

- component: dashboard-widget
  props:
    options:
      row: 1
      col: 5
      rowSpan: 2
      colSpan: 4
      title: Metric 2

- component: dashboard-widget
  props:
    options:
      row: 1
      col: 9
      rowSpan: 2
      colSpan: 4
      title: Metric 3

Main Content with Sidebar

# Large main area with narrow sidebar
- component: dashboard-widget
  props:
    options:
      row: 1
      col: 1
      rowSpan: 12
      colSpan: 9
      title: Main Content

- component: dashboard-widget
  props:
    options:
      row: 1
      col: 10
      rowSpan: 12
      colSpan: 3
      title: Sidebar

Related Topics

• Dashboard Component - Parent container for dashboard widgets
• Layout Component - Can be used as child content
• DataGrid Component - Common widget content
• Summary Component - Display metrics in widgets