Skip to main content

widgets.json

The widgets.json file is the bridge between your backend and OpenBB Terminal widgets. Each entry in this file will directly map to a widget in the app. You can find examples here.

Below are all of the values you can set along with a description for each.

NameTypeDescription
namestring (required)The display name of the widget shown to the user. Example: "Chains chart example".
descriptionstring (required)A brief description of the widget for user info and selection menu. Example: "Get current TVL of all chains and plot it!".
endpointstring (required)The backend API endpoint for retrieving data. Example: "chains". Possible values: Any valid API endpoint path as a string.
categorystringThe category for organizing widgets. Example: "crypto". Possible values: Any string representing a category.
subCategorystringSecondary category for refining search results. Example: "fundamentals".
defaultVizstringDefault visualization type for the widget. Possible values: "chart", "table". Default: "table".
gridData.wnumberThe width of the widget in grid units. Example: 20. Possible values: Any positive integer. Maximum value : 40
gridData.hnumberThe height of the widget in grid units. Example: 9. Possible values: Any positive integer. Maximum value : 100
data.dataKeystringA key to identify the data within the widget. Example: "customDataKey". Possible values: Any string representing a data key.
data.table.enableChartsbooleanEnables chart visualization for table data. Example: true. Possible values: true, false.
data.table.showAllbooleanDisplays all available data in the table. Example: true. Possible values: true, false.
data.table.chartView.enabledbooleanSets the chart view as the default view. Example: true. Possible values: true, false.
data.table.chartView.chartTypestringSpecifies the type of chart to display. Example: "column". Possible values: ChartView chart types
data.table.columnsDefsobject[]A list of the column definitions to be configured for the widget.
data.table.columnsDefs.fieldstringThe name of the field from the JSON data. Example: "column1". Possible values: Any string matching a key in the data source.
data.table.columnsDefs.headerNamestringThe display name of the column header. Example: "Column 1". Possible values: Any string.
data.table.columnsDefs.chartDataTypestringSpecifies how data is treated in a chart. Example: "category". Possible values: "category", "series", "time", "excluded".
data.table.columnsDefs.cellDataTypestringSpecifies the data type of the cell. Example: "text". Possible values: "text", "number", "boolean", "date", "dateString", "object".
data.table.columnsDefs.formatterFnstringSpecifies how to format the data. Example: "int". Possible values: formatterFn
data.table.columnsDefs.renderFnstringSpecifies a rendering function for cell data. Example: "titleCase". Possible values: "greenRed", "titleCase".
data.table.columnsDefs.widthnumberSpecifies the width of the column in pixels. Example: 100. Possible values: Any positive integer.
data.table.columnsDefs.maxWidthnumberSpecifies the maximum width of the column in pixels. Example: 200. Possible values: Any positive integer.
data.table.columnsDefs.minWidthnumberSpecifies the minimum width of the column in pixels. Example: 50. Possible values: Any positive integer.
data.table.columnsDefs.hidebooleanHides the column from the table. Example: false. Possible values: true, false.
data.table.columnsDefs.pinnedstringPins the column to the left or right of the table. Example: "left". Possible values: "left", "right".
paramsobject[]A list of query parameters that can be configured for the widget - these will be passed to your API.
params.typestringThe type of the parameter. Example: "date". Possible values: "date", "text", "ticker", "number", "boolean". (note: ticker will use our equity list)
params.paramNamestringThe name of the parameter in the URL. Example: "startDate". Possible values: Any string representing a query parameter name.
params.valuestring, number, booleanThe default value of the parameter. Example: "2024-01-01". Possible values : "text", "number", "boolean", DateModifierValue
params.labelstringThe label to display in the UI for the parameter. Example: "Start Date". Possible values: Any string.
params.showbooleanDisplays the parameter in the UI. Example: true. Possible values: true, false.
params.descriptionstringDescription of the parameter, shown on hover. Example: "The start date for the data". Possible values: Any string.
params.multiSelectbooleanIf you want to allow multiple values to be selected from your parameter options Possible values: Possible values: true, false.
params.options.labelstringThe label for a dropdown option. Example: "Option 1". Possible values: Any string.
params.options.valuestring, number, booleanThe value for a dropdown option. Example: "option1". Possible values: A value corresponding to the type.
sourcearray of stringsSpecifies the data source(s) for the widget. Example: ["API", "Database"]. Possible values: Any string describing a data source.
refetchIntervalnumberTime in milliseconds before the widget's data will refresh if on the page - default: 900000 (15m)
staleTimenumberTime in milliseconds before the widget's data is considered stale and will refresh on the next visit to the dashboard. default: 300000. milliseconds. (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.

{
"custom_widget": {
"name": "Custom Widget Example",
"description": "A widget to demonstrate custom configuration",
"endpoint": "custom-endpoint",
"data": {
"dataKey": "customDataKey",
"table": {
"enableCharts": true,
"showAll": true,
"chartView": {
"enabled": true,
"chartType": "column"
},
"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
}
]
}
},
"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"
],
"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 substract 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.