Widgets.json Overview

The widgets.json file is your configuration file that connects custom backend data to the widgets displayed in the application. Key components include:

• Basic Information: Defines the widget's name, description, and API endpoint that the data comes from.
• Metadata: Provide categories for organization and AI enhancement.
• Display Settings: Specifies widget type and grid dimensions.
• Data Configuration: Details table and chart settings, including column level information and data types.
• Parameters: Details query parameters that can be passed to the API endpoint for customization.

Each entry in this file will directly map to a widget in the app. You can find example backends here, where each folder contains a widgets.json file specifying the available widgets.

Below are all of the configurable fields and their descriptions.

A Widgets.json table is a configuration structure with any of the named attributes listed below.

Attributes

• name Type: string (required) Sets the display name of the widget shown to the user. Example: "Options EOD Data"

• description Type: string (required) Provides a brief description of the widget for user info and selection menu. This is important for Copilot to understand what the widget does. Example: "Provides EOD data for all options chains for a given ticker."

• endpoint Type: string (required) Specifies the backend API endpoint for retrieving data. Example: "chains" Possible values: Any valid API endpoint path as a string.

• wsEndpoint Type: string Specifies the WebSocket endpoint for live data updates. Only used with the Live Grid Widget. Example: "ws"

• category Type: string Defines the category for organizing widgets. Example: "Equity" Possible values: Any string representing a category.

• subCategory Type: string Provides a secondary category for refining search results. Example: "Options"

• imgUrl Type: string Image URL for the widget - will show a preview when hovering in search/add widget menu. Example: "https://myexample-imagelink.xyw/widget1"

• type Type: string Sets the default visualization type for the widget. Possible values: "chart", "table", "table_ssrm", "markdown", "metric", "note", "multi_file_viewer", "live_grid", "newsfeed", "advanced-chart", "chart-highcharts" Default: "table"

• raw Type: boolean ONLY used for Plotly configuration. If true will create a button on the widget to switch between the chart and raw data. Possible values: true, false Default: false

• runButton Type: boolean If true, a run button will be displayed instead of the refresh button. Possible values: true, false Default: false

• gridData Type: object containing the following keys:

  • w Type: number Sets the width of the widget in grid units. Example: 20 Maximum value: 40

  • h Type: number Sets the height of the widget in grid units. Example: 9 Maximum value: 100

  • minW Type: number Sets the minimum width of the widget in grid units. Example: 10

  • minH Type: number Sets the minimum height of the widget in grid units. Example: 10

  • maxW Type: number Sets the maximum width of the widget in grid units. Example: 40

  • maxH
    Type: number Sets the maximum height of the widget in grid units. Example: 100

• data Type: object containing the following keys - This key is only used for widgets that utilize the AgGrid Table:

  • dataKey Type: string A key to identify the data within the widget. Example: "customDataKey"

  • wsRowIdColumn Type: string The column that will be used to identify the row. This is important to set correctly to ensure the live updates are displayed correctly. This the key between your ws and the initial data. Only used with the Live Grid Widget. Example: "symbol"

  • table Type: object containing the following keys:

    • enableCharts Type: boolean Enables chart visualization for table data. Example: true

    • showAll Type: boolean Displays all available data in the table. Example: true

    • transpose Type: boolean Displays transpose the data in the table. Example: true

    • chartView Type: object containing the following keys:

      • enabled Type: boolean Sets the chart view as the default view. Example: true

      • chartType Type: string Specifies the type of chart to display. Example: "column" Possible values: see ChartView chart types

      • cellRangeCols Type: object Defines the default column mappings for different chart types. Each key represents a chart type, and the value is an array of column names that specify the category and series columns for that chart type. The array structure is: [category, series1, series2, ...] where:

        • First element: The category column (x-axis)
        • Remaining elements: The series columns (y-axis data) Example:

        "cellRangeCols": {
          "line": ["ticker", "weight", "weight2"],
          "column": ["date", "price", "volume"]
        }

      • ignoreCellRange Type: boolean Ignores stored cell range for the chart. Example: false

    • columnsDefs Type: list of objects, each containing the following keys:

      • field Type: string The name of the field from the JSON data. Example: "column1"

      • headerName Type: string The display name of the column header. Example: "Column 1"

      • chartDataType Type: string Specifies how data is treated in a chart. Example: "category" Possible values: "category", "series", "time", "excluded"

      • cellDataType Type: string Specifies the data type of the cell. Example: "text" Possible values: "text", "number", "boolean", "date", "dateString", "object"

      • align Type: string Specifies the alignment of the text on the cell. Example: "center" Possible values: "left", "center", "right"

      • enableCellChangeWs Type: boolean Controls whether the cell can be updated via WebSocket messages. Only used with the Live Grid Widget. Default: true Example: false

      • formatterFn Type: string Specifies how to format the data. Example: "int" Possible values: see formatterFn

      • renderFn Type: string or array Specifies a rendering function for cell data. See Render Functions for more information. Example: "titleCase" Possible values: "greenRed", "titleCase", "hoverCard", "cellOnClick", "columnColor", "showCellChange"

      • renderFnParams Type: object Required if renderFn is used. Specifies the parameters for the render function. Example: {"actionType": "sendToAgent", "sendToAgent": {"markdown": "Analyze **{company}** data"}}

        • actionType Type: string Specifies the action type for the render function. Example: "sendToAgent" Possible values: "groupBy", "sendToAgent"

        • groupBy Type: object Configuration for cell click grouping. Required when actionType is "groupBy". Contains the following keys:

          • paramName Type: string (required) The parameter name to update when a cell is clicked. Example: "symbol"

          • valueField Type: string (optional) Alternative field name to use for the parameter value (if different from the cell field). Use this when the cell displays one value (e.g., a company name) but you need to pass a different value (e.g., an ID) to the parameter. Example: "id" Example use case: If your table displays company names in the cell but your API expects company IDs, set valueField: "companyId" to use the ID field from the row data instead of the displayed name.

        • colorValueKey Type: string Specifies which field to use for determining the color when showing cell changes. Example: "Analyst"

        • hoverCardData Type: array of strings Specifies columns to show in the hover card. Example: ["column1", "column2"]

        • colorRules Type: array of objects An array of rules for conditional coloring. Each object contains the following keys:

          • condition Type: string (required) The condition for applying the color. Possible values: "eq", "ne", "gt", "lt", "gte", "lte", "between", "contains", "notContains" Description:

            • "eq" - Equal to
            • "ne" - Not equal to
            • "gt" - Greater than
            • "lt" - Less than
            • "gte" - Greater than or equal to
            • "lte" - Less than or equal to
            • "between" - Between two values (requires range object)
            • "contains" - String contains the value (case-sensitive)
            • "notContains" - String does not contain the value (case-sensitive)

          • value Type: number or string The value for the condition. For contains and notContains, use a string value. Example: 50 or "Active"

          • range Type: object (required for "between" condition) An object specifying min and max values for the between condition. Example: {"min": 50, "max": 90}

          • color Type: string (required) The color to apply. Example: "green", "red", "blue", or hex code like "#22c55e"

          • fill Type: boolean Indicates if the color should fill the cell. Example: true

          Example: [{"condition": "gt", "value": 50, "color": "green", "fill": true}] Example with contains: [{"condition": "contains", "value": "Active", "color": "green", "fill": true}]

        • hoverCard Type: object Hover card configuration. Contains the following keys:

          • cellField Type: string Field to display on table cell. Example: "value"

          • title Type: string Title for the hover card. Example: "Analyst Details"

          • markdown Type: string Markdown content for the hover card. Example: "### {value}\n- **Description:** {description}"

        • sendToAgent Type: object Configuration for sending data to an AI agent. Contains the following keys:

          • markdown Type: string Markdown content to send to the agent, supports template variables from row data using curly braces. Example: "Please analyze the company **{company}** with revenue of ${revenue}M"

          • agentId Type: string (Optional) Specific agent ID to send the message to. Example: "financial-analyst-agent"

      • width Type: number Specifies the width of the column in pixels. Example: 100

      • maxWidth Type: number Specifies the maximum width of the column in pixels. Example: 200

      • minWidth Type: number Specifies the minimum width of the column in pixels. Example: 50

      • hide Type: boolean Hides the column from the table. Example: false

      • pinned Type: string Pins the column to the left or right of the table. Example: "left" Possible values: "left", "right"

      • headerTooltip Type: string Tooltip text for the column header. Example: "This is a tooltip"

      • prefix Type: string Prefix to be added to the column header. Example: "$"

      • suffix Type: string Suffix to be added to the column header. Example: "USD"

      • sparkline Type: object Configuration for displaying sparklines within table cells. Contains the following keys:

        • type Type: string Specifies the type of sparkline chart. Example: "line" Possible values: "line", "area", "bar"

        • dataField Type: string Alternative field name to use for sparkline data (if different from main field). Example: "spark_data"

        • options Type: object Configuration options for the sparkline appearance and behavior. Contains the following keys:

          • stroke Type: string Color of the line or border. Example: "#3366cc"

          • strokeWidth Type: number Width of the line or border in pixels. Example: 2

          • fill Type: string Fill color for area and bar charts. Example: "#e3f2fd"

          • fillOpacity Type: number Opacity of the fill color (0-1). Example: 0.3

          • min Type: number Minimum value constraint for the sparkline. Example: 0

          • max Type: number Maximum value constraint for the sparkline. Example: 100

          • direction Type: string Direction for bar charts. Example: "vertical" Possible values: "vertical", "horizontal"

          • markers Type: object Configuration for markers on line and area charts. Contains the following keys:

            • enabled Type: boolean Whether to show markers. Example: true

            • size Type: number Size of the markers in pixels. Example: 3

            • fill Type: string Fill color of the markers. Example: "#3366cc"

            • stroke Type: string Stroke color of the markers. Example: "#ffffff"

            • strokeWidth Type: number Width of the marker stroke. Example: 1

          • pointsOfInterest Type: object Configuration for highlighting special data points. Contains the following keys:

            • firstLast Type: object Styling for first and last data points. Contains fill, stroke, strokeWidth, and size properties.

            • minimum Type: object Styling for minimum value points. Contains fill, stroke, strokeWidth, and size properties.

            • maximum Type: object Styling for maximum value points. Contains fill, stroke, strokeWidth, and size properties.

            • highlighted Type: object Styling for highlighted points on hover/interaction. Contains fill, stroke, strokeWidth, and size properties.

            • positiveNegative Type: object Separate styling for positive and negative values. Contains the following keys:

              • positive Type: object Styling for positive values. Contains fill, stroke, strokeWidth, and size properties.

              • negative Type: object Styling for negative values. Contains fill, stroke, strokeWidth, and size properties.

          • customFormatter Type: string JavaScript function as a string for complete control over individual data point styling. Example: "(params) => ({ fill: params.yValue >= 0 ? '#22c55e' : '#ef4444', stroke: params.yValue >= 0 ? '#16a34a' : '#dc2626' })"

          • padding Type: object Padding configuration for the sparkline. Contains the following keys:

            • top Type: number Top padding in pixels. Example: 5

            • right Type: number Right padding in pixels. Example: 5

            • bottom Type: number Bottom padding in pixels. Example: 5

            • left Type: number Left padding in pixels. Example: 5

• params Type: list of objects, each containing the following keys:

  • type Type: string The type of the parameter. Example: "date" Possible values: "date", "text", "ticker", "number", "boolean", "endpoint", "form"

  • paramName Type: string The name of the parameter in the URL. Example: "startDate"

  • value Type: string, number, boolean The default value of the parameter. Example: "2024-01-01"

  • label Type: string The label to display in the UI for the parameter. Example: "Start Date"

  • optionsEndpoint Type: string Endpoint to fetch options for the parameter. Example: "v1/test/values"

  • multiple Type: boolean If true, the parameter will be a dropdown with multiple selectable options that you can add add-hoc. Example: true

  • optionsParams Type: object Parameters to pass to the options endpoint. You can use the parameter name from the params array to pass a value to the options endpoint. Example: {"type": "$type"}

  • show Type: boolean Displays the parameter in the UI. Example: true

  • description Type: string Description of the parameter, shown on hover. Example: "The start date for the data"

  • roles Type: array Only used on the Multi-File Viewer Widget - Specifies which parameter is used to select the files. Example: ["fileSelector"]

  • multiSelect Type: boolean Allows multiple values to be selected from your parameter options. Example: true

  • style Type: object Styling options for the parameter. Only popupWidth is currently supported minimum value is 200px max value is 1000px. Example: {"popupWidth": 450}

  • options Type: list of objects, each containing the following keys:

    • label Type: string The label for a dropdown option. Example: "Option 1"

    • value Type: string, number, boolean The value for a dropdown option. Example: "option1"

    • extraInfo Type: object Additional information to display for the dropdown option. Example: {"description": "Technology Company", "rightOfDescription": "NASDAQ"}

      Contains the following keys:

      • description Type: string Additional descriptive text shown below the label. Example: "Technology Company"

      • rightOfDescription Type: string Text shown to the right of the description. Example: "NASDAQ"

• source Type: array of strings Specifies the data source(s) for the widget. Example: ["API", "Database"]

• mcp_tool Type: object Configuration for matching the widget to an MCP (Model Context Protocol) tool. When an MCP tool is invoked, OpenBB Workspace can automatically detect if there's a matching widget configured and provide a citation. Contains the following keys:

  • mcp_server Type: string (required) The name of the MCP server that must match exactly with the connected MCP server name. Example: "Financial Data"

  • tool_id Type: string (required) The ID of the MCP tool that must match exactly with the tool name in the MCP server. Example: "get_company_revenue_data"

• refetchInterval Type: number or false Time in milliseconds before the widget's data will refresh if on the page. Minimum value is 1000. Default: 900000 (15m)

• staleTime Type: number Time in milliseconds before the widget's data is considered stale and will refresh on the next visit to the dashboard. Default: 300000 (5m)

Example widgets.json

Below is an example widgets.json with a single widget defined. This widget will default to a column chart but have the ability to switch between a table and chart view. The widget will have a start date parameter, a ticker parameter, and a colors parameter, all of which will be able to be selected on the widget in the application.

{
    "custom_widget": {
        "name": "Custom Widget Example",
        "description": "A widget to demonstrate custom configuration",
        "endpoint": "custom-endpoint",
        "runButton": false,
        "data": {
            "dataKey": "customDataKey",
            "table": {
                "enableCharts": true,
                "showAll": true,
                "chartView": {
                    "enabled": true,
                    "chartType": "column",
                    "cellRangeCols" : {
                        "line": ["ticker", "weight"]
                    }
                },
                "columnsDefs": [
                    {
                        "field": "column1",
                        "headerName": "Column 1",
                        "chartDataType": "category",
                        "cellDataType": "text",
                        "formatterFn": "none",
                        "renderFn": "titleCase",
                        "width": 100,
                        "maxWidth": 200,
                        "minWidth": 50,
                        "hide": false,
                        "pinned": "left"
                    },
                    {
                        "field": "column2",
                        "headerName": "Column 2",
                        "chartDataType": "series",
                        "cellDataType": "number",
                        "formatterFn": "int",
                        "renderFn": "greenRed",
                        "width": 150
                    },
                    {
                        "field": "status",
                        "headerName": "Status",
                        "cellDataType": "text",
                        "renderFn": "columnColor",
                        "renderFnParams": {
                            "colorRules": [
                                {
                                    "condition": "contains",
                                    "value": "Active",
                                    "color": "green",
                                    "fill": true
                                },
                                {
                                    "condition": "contains",
                                    "value": "Pending",
                                    "color": "yellow",
                                    "fill": true
                                },
                                {
                                    "condition": "notContains",
                                    "value": "Active",
                                    "color": "red",
                                    "fill": true
                                }
                            ]
                        },
                        "width": 150
                    },
                    {
                        "field": "companyName",
                        "headerName": "Company",
                        "cellDataType": "text",
                        "renderFn": "cellOnClick",
                        "renderFnParams": {
                            "actionType": "groupBy",
                            "groupBy": {
                                "paramName": "companyId",
                                "valueField": "companyId"
                            }
                        },
                        "width": 200
                    },
                {
                    "field": "price_trend",
                    "headerName": "Price Trend",
                    "width": 200,
                    "sparkline": {
                        "type": "line",
                        "options": {
                            "stroke": "#3366cc",
                            "strokeWidth": 2,
                            "markers": {
                                "enabled": true,
                                "size": 3
                            },
                            "pointsOfInterest": {
                                "maximum": {
                                    "fill": "#22c55e",
                                    "stroke": "#16a34a",
                                    "size": 5
                                },
                                "minimum": {
                                    "fill": "#ef4444",
                                    "stroke": "#dc2626",
                                    "size": 5
                                }
                            }
                        }
                    }
                }
                ]
            }
        },
        "params": [
            {
                "type": "date",
                "paramName": "startDate",
                "value": "2024-01-01",
                "label": "Start Date",
                "show": true,
                "description": "The start date for the data",
            },
            {
                "type": "text",
                "paramName": "ticker",
                "value": "AAPL",
                "label": "Ticker",
                "show": true,
                "description": "Stock ticker symbol",
            },
            {
                "type": "text",
                "paramName": "colors",
                "value": "red",
                "label": "Colors",
                "show": true,
                "description": "Stock ticker symbol",
                "multiSelect": true,
                "options": [
                  { "label": "Red", "value": "red" },
                  { "label": "Green", "value": "green" },
                  { "label": "Blue", "value": "blue" }
                ],
            }
        ],
        "source": [
            "My First API"
        ],
        "mcp_tool": {
            "mcp_server": "Financial Data",
            "tool_id": "get_company_revenue_data"
        },
        "refetchInterval" : 900000,
        "staleTime": 300000
    }
}

Special Properties

Date Modifier

This is used to display a dynamic date.

The reference is $currentDate and if a user wants to add or subtract they need to append to the variable:

• h, for hour
• d, for day
• w, for week
• M, for month
• y, for year

For instance, $currentDate-1w stands for 1 week ago.

If you don't want to set a date you can omit the value parameter or pass null.

Examples

[
  {
    "paramName": "start_date",
    "value": "$currentDate-2y",
    "label": "Start Date",
    "type": "date",
    "description": "Current Date for the stock price"
  },
  {
    "paramName": "end_date",
    "value": "$currentDate+1d",
    "label": "End Date",
    "type": "date",
    "description": "End Date for the stock price"
  },
    {
    "paramName": "end_date",
    "value": null,
    "label": "End Date",
    "type": "date",
    "description": "End Date for the stock price"
  },
  {
    "paramName": "interval",
    "value": "1d",
    "label": "Interval",
    "options": [
      { "label": "Daily", "value": "1d" },
      { "label": "Weekly", "value": "1w" },
      { "label": "Monthly", "value": "1m" }
    ],
    "type": "text",
    "description": "Select the interval"
  }
]

ChartView chart types

chartType: The type of chart to display by default. These charts are provided using the AgGrid library. Custom charts can also be created using Plotly. For examples, refer to the GitHub repository.

Allowed values: column, groupedColumn, stackedColumn, normalizedColumn, bar, groupedBar, stackedBar, normalizedBar, line, scatter, bubble, pie, donut, doughnut, area, stackedArea, normalizedArea, histogram, radarLine, radarArea, nightingale, radialColumn, radialBar, sunburst, rangeBar, rangeArea, boxPlot, treemap, heatmap, waterfall

formatterFn

formatterFn (optional): Specifies the function used to format the data in the table. The following values are allowed:

• int: Formats the number as an integer.
• none: Does not format the number.
• percent: Adds % to the number.
• normalized: Multiplies the number by 100.
• normalizedPercent: Multiplies the number by 100 and adds % (e.g., 0.5 becomes 50 %).
• dateToYear: Converts a date to just the year.