---
title: Dashboard
description: Dashboard protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Color variant for dashboard widgets (e.g., KPI cards).

<Callout type="info">
**Source:** `packages/spec/src/ui/dashboard.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant } from '@objectstack/spec/ui';
import type { Dashboard, DashboardHeader, DashboardHeaderAction, DashboardWidget, GlobalFilter, GlobalFilterOptionsFrom, WidgetActionType, WidgetColorVariant } from '@objectstack/spec/ui';

// Validate data
const result = Dashboard.parse(data);
```

---

## Dashboard

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Dashboard unique name |
| **label** | `string` | ✅ | Dashboard label |
| **description** | `string` | optional | Dashboard description |
| **header** | `Object` | optional | Dashboard header configuration |
| **widgets** | `Object[]` | ✅ | Widgets to display |
| **columns** | `integer` | optional | Number of grid columns (default 12) |
| **gap** | `integer` | optional | Grid gap in Tailwind spacing units |
| **refreshInterval** | `number` | optional | Auto-refresh interval in seconds |
| **dateRange** | `Object` | optional | Global dashboard date range filter configuration |
| **globalFilters** | `Object[]` | optional | Global filters that apply to all widgets in the dashboard |
| **aria** | `Object` | optional | ARIA accessibility attributes |
| **performance** | `Object` | optional | Performance optimization settings |
| **protection** | `Object` | optional | Package author protection block — lock policy for this dashboard. |
| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact | package | env-forced). |
| **_provenance** | `Enum<'package' \| 'org' \| 'env-forced'>` | optional | Origin of the item (package | org | env-forced). |
| **_packageId** | `string` | optional | Owning package machine id. |
| **_packageVersion** | `string` | optional | Owning package version. |
| **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |


---

## DashboardHeader

Dashboard header configuration

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **showTitle** | `boolean` | ✅ | Show dashboard title in header |
| **showDescription** | `boolean` | ✅ | Show dashboard description in header |
| **actions** | `Object[]` | optional | Header action buttons |


---

## DashboardHeaderAction

Dashboard header action

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **label** | `string` | ✅ | Action button label |
| **actionUrl** | `string` | ✅ | URL or target for the action |
| **actionType** | `Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>` | optional | Type of action |
| **icon** | `string` | optional | Icon identifier for the action button |


---

## DashboardWidget

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Unique widget identifier (snake_case) |
| **title** | `string` | optional | Widget title |
| **description** | `string` | optional | Widget description text below the header |
| **type** | `Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| 'funnel' \| 'scatter' \| 'treemap' \| 'sankey' \| 'gauge' \| 'solid-gauge' \| 'metric' \| 'kpi' \| 'bullet' \| 'radar' \| 'table' \| 'pivot'>` | ✅ | Visualization type |
| **chartConfig** | `Object` | optional | Chart visualization configuration |
| **colorVariant** | `Enum<'default' \| 'blue' \| 'teal' \| 'orange' \| 'purple' \| 'success' \| 'warning' \| 'danger'>` | optional | Widget color variant for theming |
| **requiresObject** | `string` | optional | Hide the widget unless the named object is registered |
| **requiresService** | `string` | optional | Hide the widget unless the named kernel service is registered |
| **actionUrl** | `string` | optional | URL or target for the widget action button |
| **actionType** | `Enum<'script' \| 'url' \| 'modal' \| 'flow' \| 'api'>` | optional | Type of action for the widget action button |
| **actionIcon** | `string` | optional | Icon identifier for the widget action button |
| **filter** | `[__schema0](./__schema0)` | optional | Presentation-scope filter (runtimeFilter) |
| **compareTo** | `string \| string \| Object` | optional | Period-over-period comparison window |
| **dataset** | `string` | ✅ | Dataset name to bind (ADR-0021) |
| **dimensions** | `string[]` | optional | Dimension names — X/group/split |
| **values** | `string[]` | ✅ | Measure names — Y (at least one) |
| **layout** | `Object` | ✅ | Grid layout position |
| **options** | `any` | optional | Widget specific configuration |
| **suppressWarnings** | `string[]` | optional | Build diagnostic rule ids suppressed on this widget |
| **responsive** | `Object` | optional | Responsive layout configuration |
| **aria** | `Object` | optional | ARIA accessibility attributes |


---

## GlobalFilter

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **field** | `string` | ✅ | Field name to filter on |
| **label** | `string` | optional | Display label for the filter |
| **type** | `Enum<'text' \| 'select' \| 'date' \| 'number' \| 'lookup'>` | optional | Filter input type |
| **options** | `Object[]` | optional | Static filter options |
| **optionsFrom** | `Object` | optional | Dynamic filter options from object |
| **defaultValue** | `string \| number \| boolean` | optional | Default filter value |
| **scope** | `Enum<'dashboard' \| 'widget'>` | ✅ | Filter application scope |
| **targetWidgets** | `string[]` | optional | Widget IDs to apply this filter to |


---

## GlobalFilterOptionsFrom

Dynamic filter options from object

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **object** | `string` | ✅ | Source object name |
| **valueField** | `string` | ✅ | Field to use as option value |
| **labelField** | `string` | ✅ | Field to use as option label |
| **filter** | `[__schema0](./__schema0)` | optional | Filter to apply to source object |


---

## WidgetActionType

Widget action type

### Allowed Values

* `script`
* `url`
* `modal`
* `flow`
* `api`


---

## WidgetColorVariant

Widget color variant

### Allowed Values

* `default`
* `blue`
* `teal`
* `orange`
* `purple`
* `success`
* `warning`
* `danger`


---

