Custom widgets allow you to add your own widgets to AG Studio. Use them when the provided widgets do not meet your requirements.
The example above demonstrates a custom widget showing a single data value.
Implementing a Custom Widget Copy Link
To provide a custom widget, implement the AgWidgetDefinition interface.
Unique widget identifier (e.g., 'grid', 'value', 'column-chart-grouped'). |
Display label, or localisation key. |
Optional icon for widget display. One of: string - an SVG string { className: string } - A CSS class name { url: string } - A URL to an SVG |
Optional data mappings for the widget (if required). This defines the type of fields and how they are used by the widget.
|
Optional format shape. The shape created by this function will be used for parsing the format configuration. If provided, format state will be passed through the parse() method before being loaded into Studio. If using AI, the shape is required, as it uses the schema.
|
Form configuration using typed form builder. |
Optional default state. If provided, this will override the default values in the form. It also allows defaults to be set for the data mapping and sort.
|
Optional default widget ID that this definition extends. Use this if overriding or pre-configuring one of the default widgets. This ensure that any values that no longer appear in the form are still correctly mapped / set to the right default value. For custom widgets, this should not be set.
|
Custom component Either: a string that matches a Vue custom component; a custom Vue component; or a custom TypeScript component class (no Vue; working directly with the DOM). |
Default widget size when created. |
Minimum widget size constraints. |
Optional toolbar configuration. Can be a built-in item ( 'delete' or 'duplicate') or a custom item. If the item provides an action, that will be performed, otherwise it will be dispatched as a 'toolbarAction' event to the widget. If providing a custom value, 'duplicate' and 'delete' must be provided if required. |
Optional frame style (defaults to standard widget frame). |
Optional feature configuration. |
Optional options passed directly to widget. |
Optional structured AI metadata for this widget type. |
Custom widgets are provided to the widgets property, similar to Customising the Available Widgets.
Provide the custom widget definitions to the createWidgets(params) helper function, and add them to the menu.
<ag-studio
:widgets="widgets"
/* other studio properties ... */>
</ag-studio>
this.widgets = (widgetConfig) => createWidgets<CustomRegistry>({
additionalTypes: [customWidgetDefinition],
menu: [
...widgetConfig.menu,
{
label: 'Custom',
widgetIds: ['customWidget'],
},
]
});For the types to work correctly, the custom widgets should be defined in the Registry Type.
interface CustomRegistry extends AgBaseRegistry {
widgets: readonly (AgDefaultWidgetDefinition | CustomWidgetDefinition)[]
} Data Mapping Copy Link
The dataMapping property defines the fields or fieldsets that are required to configure the widget, and the required relationships between them.
For example, to configure a line chart, the data mapping might look like this:
const dataMapping = {
xAxisKey: {
type: 'field', // Only a single field allowed
// All types of value allowed
supportedRoles: ['category', 'numeric', 'temporal'],
requires: { cardinality: 'many' }, // Many values are accepted
required: true, // Required field - widget cannot be displayed without it
sort: true, // Show the sort menu
aiDescription: 'Field for the x axis.', // Description when used with AI
},
yAxisKey: {
type: 'fieldset', // Multiple fields allowed
supportedRoles: ['numeric'], // Only numeric values allowed
// For each `xAxisKey`, this must map to a single value
requires: { per: 'dataMapping.xAxisKey', cardinality: 'one' },
required: true, // Required field - widget cannot be displayed without it
sort: true, // Show the sort menu
// Description when used with AI
aiDescription: 'Field(s) for the y axis. Each field becomes a separate series.',
},
}; Custom Widget Component Copy Link
The custom component is a Vue component that receives params of type AgWidgetParams, and has a refresh(params) method that is called when the params are updated.
Widget ID. |
Widget type. |
Widget format as constructed from the widget form. |
Widget data mapping values. |
Widget sort if defined. |
Widget configuration. |
Widget API. Provides access to retrieve data. |
Studio API. |
Application context as set on context Studio property. |
Custom Widget Params Copy Link
Widget configuration. |
Widget API. Provides access to retrieve data. |
Studio API. |
Application context as set on context Studio property. |
Display State Copy Link
Widgets have four different display states that can be set via widgetApi.setDisplayState(state, metadata?). These will trigger different overlays to be displayed by the layout on top of the widget. The states are:
displayed- The widget has data and is ready to display. Studio will show no overlay; the widget is rendered normally.loading- The widget is loading. Metadata defaults to{ prominent: true }for a solid loading overlay; use{ prominent: false }for an unobtrusive refresh indicator that keeps the previous content visible.noData- The widget has no data (e.g. everything is filtered out or the data is empty). Studio will show an overlay with "No data to display".incompleteDataMapping- The widget does not have all of the required fields set. Studio will show an overlay with the field selection inputs.
Each time the widget updates, set the relevant status as needed.
widgetApi.setDisplayState('loading');
const response = await widgetApi.getData(request);
// ... process the response
widgetApi.setDisplayState('displayed'); Loading Data Copy Link
Data is loaded via widgetApi.getData(request). The request can be constructed from the data mapping values in the params.
Flat row query. Omit for backwards compatibility. |
List of fields to return in the query. Unaggregated fields will automatically be used for grouping. |
Sort the result based on the provided fields. |
Additional filter to apply. Page-level filters and widget-level filters (including from filter widgets and cross filters) will be automatically applied.
|
Limit the number of rows returned, or for pagination.
|
Form Copy Link
The widget form configures the form displayed in the edit panel. The values from the form are passed in the widget params.
See the Form Setup page for more details.
Cross-Filtering Copy Link
To implement cross-filtering from within a custom widget, the cross filter methods can be used from the widget API.
Set a cross filter. |
Clear cross filter. |
Get the current cross filter for this widget. |
To support the cross filter highlight behaviour (similar to some of the default charts, e.g. column charts), enable it in the widget definition.
const widgetDefinition = {
// ...
featureConfig: {
crossFilter: {
supportsHighlight: true
}
}
};When this is enabled, the data response will contain two datasets. The original data (response.results), and the cross-filtered data (response.crossFilter).
AI Integration Copy Link
For a custom widget to work with AI, the formatShape and ai properties must be defined in the widget definition.
The shape returned by formatShape is used to provide the AI with the schema for the format property of the widget, and to validate the format value the AI sets via state.
Using AG Grid and AG Charts in Custom Widgets Copy Link
As well as the built-in AG Grid and AG Charts widgets, it is possible to create your own custom widgets using AG Grid and AG Charts.
To match the AG Grid theming in Studio, use studioGridTheme and pass it to the theme grid option.
For AG Charts, set the following in chart options (where api is the Studio API in the widget params):
const chartOptions = {
// ... other options
theme: getChartTheme(api),
background: {
fill: 'transparent'
}
};Using AG Grid Enterprise or AG Charts Enterprise in a custom widget requires the relevant AG Grid Enterprise or AG Charts Enterprise licence.
Popups within Custom Widgets Copy Link
If a custom widget creates its own popup that is anchored outside of the custom widget DOM element (e.g. like a third-party date picker), then the popup element needs to have the 'ag-custom-component-popup' CSS class. This allows Studio to determine correctly when focus is within a widget.
Sankey Chart Copy Link
A Sankey diagram visualises flow between two sets of nodes, sized by a numeric measure. This example maps a sales dataset (channel → product category) and supports cross-filtering: clicking a node filters the bar chart alongside it, and holding Ctrl/Cmd adds to the selection.
The widget uses two parallel getData calls on every refresh - one that ignores cross-filters to keep the full node set stable, and one that respects them to compute which nodes and links to dim. This prevents the chart from reflowing every time a filter changes.
Choropleth Map Copy Link
A choropleth map shades geographic regions by a numeric measure. This example renders UK county boundaries using AG Charts' map-shape series and supports click-to-cross-filter alongside a regional bar chart.
The colour domain is clamped to the p10-p90 range of the dataset, preventing a single high-value region from compressing all other counties into a narrow band near the minimum. When counties are selected, a background layer renders the full distribution at reduced opacity to preserve geographic context.