Available Widget Types
VizBoard supports multiple widget types for different visualization needs:Chart Widgets
Bar, line, and area charts for visualizing trends and comparisons
Data Table Widgets
Interactive tables with sorting, filtering, and pagination
Text Widgets
Section titles and text blocks for dashboard organization
Integrated Tables
Advanced tables with complex data relationships
Widget Data Model
All widgets share a common data structure:Widget order is managed at the project level via the
orderedWidgetIds array in the Project model.Creating a Chart Widget
Chart widgets visualize data from database tables as bar charts, line charts, or area charts.Select Chart Type
Choose from:
- Bar Chart - Compare values across categories
- Line Chart - Show trends over time
- Area Chart - Visualize cumulative data
Chart Configuration Example
Chart Widget Implementation
The chart widget fetches data and renders based on configuration (src/components/dashboard/widgets/charts/chartWidget.tsx:31-288):
Expanding Charts
Charts can be expanded to take up more horizontal space:- Normal Width: 1 column on desktop (col-span-1)
- Expanded Width: 2 columns on desktop (col-span-2)
expanded state is persisted in the widget’s configs.
Creating a Data Table Widget
Data table widgets display database records in an interactive table format.Configure Connection
Database connection to query
Select Tables
List of table names to make available in the widget dropdown
Data Table Configuration Example
Data Table Features
Data table widgets include:- Column Sorting: Click column headers to sort
- Filtering: Filter by column values with type-aware filters
- Search: Global search across all columns
- Pagination: Navigate large datasets efficiently
- Table Switching: Dropdown to switch between configured tables
Data Table Implementation
Fromsrc/components/dashboard/widgets/datatable/datatableWidget.tsx:33-275:
Column Type Detection
The data table automatically detects column types from the database schema and applies appropriate:- Text Filters: For string columns
- Number Filters: For numeric columns (range, equals, greater than, etc.)
- Date Filters: For date/timestamp columns
- Boolean Filters: For boolean columns
- Array Filters: For array columns
Creating Text Widgets
Text widgets add structure and context to your dashboards without querying data.Section Title Widget
Adds a prominent heading to group related widgets:Text Block Widget
Adds descriptive text, markdown content, or notes:Widget CRUD Operations
All widget operations go through the CRUD functions insrc/app/actions/dashboard/crudWidgets.ts.
Creating a Widget
Updating a Widget
Deleting a Widget
Upserting a Widget
TheUpsertWidget function handles both create and update:
Widget Ordering
Widget display order is controlled by theorderedWidgetIds array in the Project model.
Reordering Widgets
Users can drag and drop widgets to reorder them. The new order is saved via:Default Order
IforderedWidgetIds is empty or missing widget IDs, widgets are displayed in creation order (createdAt ascending).
Widget Settings Menu
All widgets include a settings menu with common actions (src/components/dashboard/widgets/shared/widgetSettingsMenu.tsx):
- Edit: Open widget configuration dialog
- Refresh: Manually refresh widget data
- Delete: Remove widget from dashboard
- Duplicate: Create a copy of the widget (if supported)
Real-Time Data Updates
Widgets fetch data on mount and can be refreshed:Automatic Refresh
Widgets use SWR for data fetching with automatic revalidation:Manual Refresh
Click the refresh icon in the widget settings menu to manually reload data.Widget Error States
Widgets display different error states based on the situation:Configuration Incomplete
Required configuration fields are missing (e.g., no table selected)
Offline
No internet connection detected
Loading
Data is being fetched from the database
Error
Failed to fetch data (connection error, query error, etc.)
No Data
Query successful but returned zero rows
Error State Implementation
From the chart widget (src/components/dashboard/widgets/charts/chartWidget.tsx:194-283):
Public Dashboard Widgets
When a project is made public, all widgets are visible to anyone with the public link.Read-Only Mode
Public dashboards are read-only:- No widget settings menu
- No edit/delete options
- No expand/collapse for charts
- Data refreshes automatically but cannot be triggered manually
Public Widget Detection
Best Practices
Meaningful Titles
Use clear, descriptive titles that explain what the widget shows
Add Descriptions
Include descriptions for complex widgets to help users understand the data
Group Related Widgets
Use text widgets to create sections and organize your dashboard
Choose Appropriate Charts
Use bar charts for comparisons, line charts for trends, tables for detailed data
Limit Y-Axis Series
Keep chart series to 3-5 max for readability
Test with Real Data
Preview widgets with actual database data before finalizing
Troubleshooting
Widget Shows “Configuration Incomplete”
- Verify all required fields are filled (connection, table, columns)
- Check that the table name exists in the database
- Ensure the connection is valid
Widget Shows “No Data Available”
- Confirm the table contains rows
- Check if filters are too restrictive
- Verify the selected columns exist
Widget Fails to Load
- Check browser console for errors
- Verify database connection is valid
- Ensure schema introspection completed successfully
- Try regenerating the project schema
Chart Displays Incorrectly
- Verify X-axis column contains unique values
- Ensure Y-axis columns contain numeric data
- Check for null values in the data
- Try a different chart type
