📦 Installation
Install the plugin from the Bubble marketplace
Drag the DashboardBuilder element onto your page
Configure the properties (see below)
Connect your data source or provide JSON data


⚙️ Properties Reference
Data Properties
PropertyTypeDescriptiondata_jsonTextJSON array with your data (see format below)use_data_sourceBooleanToggle to use Bubble's data source instead of JSONdata_sourceListBubble list from "Do a search for"data_fieldsTextComma-separated field names to extract from data_sourcedate_fieldTextName of the date field in your data (default: "date")
Layout Properties
PropertyTypeDescriptioncards_configTextJSON configuration for dashboard cards (see below)columnsNumberGrid columns (default: 12)row_heightNumberRow height in pixels (default: 80)gapNumberGap between cards in pixels (default: 16)saved_layoutTextPreviously saved layout JSON (for persistence)
Appearance Properties
PropertyTypeDescriptionthemeText"light" or "dark"primary_colorColorPrimary accent colorsecondary_colorColorSecondary accent colorsuccess_colorColorColor for positive valuesdanger_colorColorColor for negative valuescard_backgroundColorCustom card background (optional)card_radiusNumberCard border radius in pixelsfont_familyTextCSS font familycustom_colorsTextComma-separated colors for chart seriescolor_opacityNumberOpacity for chart colors (0-1)
Filter Properties
PropertyTypeDescriptiontoolbar_modeText"full", "period_only", "filters_only", "compact", or "hidden"filter_fieldsTextComma-separated field names for dropdown filtersfilter_labelsTextJSON object mapping field names to display labelsshow_period_filterBooleanShow/hide period date inputsshow_comparison_toggleBooleanShow/hide comparison togglecurrent_startDateInitial start date for period filtercurrent_endDateInitial end date for period filterprevious_startDateStart date for comparison periodprevious_endDateEnd date for comparison period
Behavior Properties
PropertyTypeDescriptionenable_dragBooleanAllow drag and drop (default: true)enable_resizeBooleanAllow card resizing (default: true)enable_comparisonBooleanEnable period comparison featureallow_card_settingsBooleanShow settings button on cardsallow_add_cardBooleanAllow adding hidden cards backhidden_cardsTextJSON array of hidden card IDs
Localization Properties
PropertyTypeDescriptionlocaleTextLocale for number/date formatting (e.g., "en-US", "pt-BR")currencyTextCurrency code (e.g., "USD", "BRL", "EUR")ui_labelsTextJSON object to customize UI text labelstarget_valueNumberGlobal target/goal value for progress cards

📊 Data Format
Option 1: JSON Data (data_json)
Provide a JSON array of objects:
json[
 {
   "date": "2025-01-05",
   "category": "Electronics",
   "product": "Smartphone",
   "seller": "John Smith",
   "quantity": 12,
   "value": 8500.00,
   "cost": 6800.00,
   "status": "delivered"
 },
 {
   "date": "2025-01-08",
   "category": "Electronics",
   "product": "Laptop",
   "seller": "Mary Johnson",
   "quantity": 5,
   "value": 12500.00,
   "cost": 9500.00,
   "status": "delivered"
 }
]
Option 2: Data Source (use_data_source = true)

Set use_data_source to yes
In data_source, use "Do a search for" to get your data
In data_fields, list the fields you want to extract:

  date,category,product,seller,quantity,value,cost,status
Note: Field names in data_fields should match your database field names exactly.

🎴 Cards Configuration
The cards_config property accepts a JSON array defining each card:
json[
 {
   "id": "unique_card_id",
   "title": "Card Title",
   "type": "kpi",
   "x": 0,
   "y": 0,
   "w": 4,
   "h": 2,
   "config": {
     "valueField": "value",
     "aggregation": "sum",
     "format": "currency"
   }
 }
]
Card Properties
PropertyDescriptionidUnique identifier for the cardtitleDisplay titletypeChart type (see below)xGrid column position (0-11)yGrid row positionwWidth in grid columnshHeight in grid rowsconfigType-specific configuration
Chart Types and Config Options
KPI Card
json{
 "type": "kpi",
 "config": {
   "valueField": "value",
   "aggregation": "sum",
   "format": "currency",
   "showComparison": true,
   "comparisonLabel": "vs last period"
 }
}
Progress Bar
json{
 "type": "progress",
 "config": {
   "valueField": "value",
   "aggregation": "sum",
   "target": 100000,
   "format": "currency"
 }
}
Gauge
json{
 "type": "gauge",
 "config": {
   "valueField": "value",
   "aggregation": "sum",
   "target": 100000,
   "format": "percent"
 }
}
Bar Chart (Vertical or Horizontal)
json{
 "type": "bar",
 "config": {
   "valueField": "value",
   "groupBy": "category",
   "aggregation": "sum",
   "format": "currency",
   "horizontal": false
 }
}
Line Chart
json{
 "type": "line",
 "config": {
   "valueField": "value",
   "groupByDate": true,
   "groupByFormat": "month",
   "aggregation": "sum",
   "format": "currency"
 }
}
Area Chart
json{
 "type": "area",
 "config": {
   "valueField": "value",
   "groupByDate": true,
   "groupByFormat": "month",
   "aggregation": "sum"
 }
}
Pie Chart
json{
 "type": "pie",
 "config": {
   "valueField": "value",
   "groupBy": "category",
   "aggregation": "sum"
 }
}
Donut Chart
json{
 "type": "donut",
 "config": {
   "valueField": "value",
   "groupBy": "seller",
   "aggregation": "sum"
 }
}
Funnel Chart
json{
 "type": "funnel",
 "config": {
   "valueField": "value",
   "groupBy": "status",
   "aggregation": "sum",
   "format": "currency"
 }
}
Stacked Bar Chart
json{
 "type": "stacked",
 "config": {
   "valueField": "value",
   "groupBy": "category",
   "seriesField": "seller",
   "aggregation": "sum",
   "format": "currency"
 }
}
Multiseries Chart
json{
 "type": "multiseries",
 "config": {
   "valueField": "value",
   "groupBy": "date",
   "seriesField": "seller",
   "aggregation": "sum",
   "format": "currency"
 }
}
Table
json{
 "type": "table",
 "config": {
   "valueField": "value",
   "groupBy": "product",
   "aggregation": "sum",
   "format": "currency",
   "sortOrder": "desc",
   "limit": 10
 }
}
Config Options Reference
OptionDescriptionValuesvalueFieldField to aggregateAny numeric field namegroupByField to group data byAny field namegroupByDateGroup by date fieldtrue/falsegroupByFormatDate grouping format"day", "week", "month", "year"seriesFieldField for multiple seriesAny field nameaggregationAggregation method"sum", "avg", "count", "min", "max"formatNumber format"number", "currency", "percent", "integer"targetTarget/goal valueNumberhorizontalHorizontal barstrue/falsesortOrderTable sort order"asc", "desc"limitTable row limitNumberstatusFilterFilter by statusString or array of stringsstatusFieldStatus field nameField name (default: "status")

📤 Exposed States
StateTypeDescriptionlayout_jsonTextCurrent layout configuration (for saving)active_filtersTextCurrent active filters as JSONperiod_startDateSelected start dateperiod_endDateSelected end dateerror_messageTextError message if anyis_loadingBooleanLoading stateprogress_currentNumberCurrent progress valueprogress_targetNumberProgress target valueprogress_percentageNumberProgress percentage

🎬 Events
EventDescriptionLayoutChangedTriggered when user moves/resizes cardsFilterChangedTriggered when filters are appliedComparisonToggledTriggered when comparison is toggledCardScreenshotTriggered when screenshot button is clicked

💾 Saving User Layouts
To persist the user's custom layout:

Save the layout:

When LayoutChanged event triggers
Get the layout_json exposed state
Save it to your database (user's record)


Restore the layout:

On page load, fetch the saved layout from database
Pass it to the saved_layout property



Example Workflow:
When LayoutChanged:
 → Make changes to Current User
 → dashboard_layout = DashboardBuilder's layout_json

On Page Load:
 → Set saved_layout = Current User's dashboard_layout

🌐 Localization
Changing UI Labels
Use the ui_labels property to customize text:
json{
 "period": "Period:",
 "until": "to",
 "apply": "Apply",
 "clear": "Clear",
 "records": "records",
 "compare_periods": "Compare periods",
 "save": "Save",
 "cancel": "Cancel"
}
Supported Locales

en-US - English (US)
en-GB - English (UK)
pt-BR - Portuguese (Brazil)
es-ES - Spanish (Spain)
fr-FR - French
de-DE - German
And any valid BCP 47 language tag


📱 Mobile Optimization
For optimal mobile experience, we recommend creating two dashboard elements:

Desktop Dashboard (visible when page width > 768px)

Full 12 cards with all features
Complete filter toolbar


Mobile Dashboard (visible when page width ≤ 768px)

3-4 essential KPI cards
Simplified or hidden toolbar
toolbar_mode: "hidden" or "compact"



Use Bubble's responsive conditions to show/hide each element.

🔧 Troubleshooting
Dashboard not rendering

Check browser console for errors
Verify data_json is valid JSON
Ensure cards_config is properly formatted
Check that date range includes your data dates

No data showing

Verify field names match exactly (case-sensitive)
Check date_field matches your date field name
Ensure current_start and current_end cover your data period

Charts empty

Confirm valueField exists in your data
Check groupBy field has valid values
Verify data is not being filtered out

Invalid language tag error

Remove any spaces from locale property
Use valid locale format: "en-US", "pt-BR", etc.


📋 Complete Example
Data JSON:
json[
 {"date": "2025-01-05", "category": "Electronics", "product": "Smartphone", "seller": "John", "value": 8500, "quantity": 12, "status": "delivered"},
 {"date": "2025-01-08", "category": "Clothing", "product": "T-Shirt", "seller": "Mary", "value": 2250, "quantity": 45, "status": "delivered"},
 {"date": "2025-02-10", "category": "Home", "product": "Blender", "seller": "John", "value": 2400, "quantity": 20, "status": "pending"}
]
Cards Config:
json[
 {
   "id": "kpi_sales",
   "title": "Total Sales",
   "type": "kpi",
   "x": 0, "y": 0, "w": 4, "h": 2,
   "config": {"valueField": "value", "aggregation": "sum", "format": "currency"}
 },
 {
   "id": "kpi_qty",
   "title": "Quantity Sold",
   "type": "kpi",
   "x": 4, "y": 0, "w": 4, "h": 2,
   "config": {"valueField": "quantity", "aggregation": "sum", "format": "integer"}
 },
 {
   "id": "chart_category",
   "title": "Sales by Category",
   "type": "bar",
   "x": 0, "y": 2, "w": 6, "h": 3,
   "config": {"valueField": "value", "groupBy": "category", "aggregation": "sum", "format": "currency"}
 },
 {
   "id": "chart_trend",
   "title": "Sales Trend",
   "type": "line",
   "x": 6, "y": 2, "w": 6, "h": 3,
   "config": {"valueField": "value", "groupByDate": true, "groupByFormat": "month", "aggregation": "sum"}
 }
]
Properties:

locale: en-US
currency: USD
theme: light
toolbar_mode: full
filter_fields: category,seller,status
date_field: date


🆘 Support
For questions, bug reports, or feature requests:

Email: [[email protected]]
Forum: [Bubble Forum Thread URL]


📄 Changelog
Version 1.0.0

Initial release
13 chart types
Drag & drop layout
Dynamic filters
Data source and JSON modes
Light/Dark themes
Layout persistence
Screenshot feature


Made with ❤️ for the Bubble community