--- product: "AG Studio" title: "Custom Widgets" description: "Custom widgets add application-defined widgets to AG Studio, for cases the provided widgets do not cover." framework: angular version: "3.0.0" related: - title: "Widgets Overview" url: "https://www.ag-grid.com/studio/archive/3.0.0/angular/widget-overview/" - title: "Configuring Widgets" url: "https://www.ag-grid.com/studio/archive/3.0.0/angular/widget-configuration/" - title: "Form Configuration" url: "https://www.ag-grid.com/studio/archive/3.0.0/angular/custom-widgets-form/" llms: "https://www.ag-grid.com/studio/archive/3.0.0/llms.txt" --- # Custom Widgets Custom widgets add application-defined widgets to AG Studio, for cases the provided widgets do not cover. #### Custom Widget ```ts import '@angular/compiler'; import { provideHttpClient } from '@angular/common/http'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component.ts'; const app = bootstrapApplication(AppComponent, { providers: [provideHttpClient()], }); ``` [Live example: Custom Widget](https://www.ag-grid.com/studio/archive/3.0.0/examples/custom-widgets/custom-widget/angular/) The example above demonstrates a custom widget showing a single data value. ## Creating a Custom Widget To provide a custom widget, implement the `AgWidgetDefinition` interface. | Property | Type | Default | Description | | --- | --- | --- | --- | | `id` | `TWidgetType` | | Unique widget identifier (e.g., 'grid', 'value', 'column-chart-grouped'). | | `label` | `string` | | Display label, or localisation key. | | `icon` | `AgCustomIcon` | | Optional icon for widget display. One of: `string` - an SVG string `{ className: string }` - A CSS class name `{ url: string }` - A URL to an SVG | | `dataMapping` | `AgDataMappingDefinitions` | | Optional data mappings for the widget (if required). This defines the type of fields and how they are used by the widget. | | `formatShape` | `Function` | | 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` | `Function` | | Form configuration using typed form builder. | | `defaultState` | `Partial` | | 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. | | `extends` | `"value" \| "grid" \| "pivot-grid" \| "column-chart-grouped" \| "column-chart-stacked" \| "column-chart-stacked-100" \| "bar-chart-grouped" \| "bar-chart-stacked" \| "bar-chart-stacked-100" \| "line-chart" \| "area-chart" \| "area-chart-stacked" \| "area-chart-stacked-100" \| "scatter-chart" \| "bubble-chart" \| "radar-line-chart" \| "radar-area-chart" \| "radial-column-chart" \| "nightingale-chart" \| "radial-bar-chart" \| "pie-chart" \| "donut-chart" \| "funnel-chart" \| "cone-funnel-chart" \| "pyramid-chart" \| "treemap-chart" \| "sunburst-chart" \| "radial-gauge" \| "linear-gauge" \| "button-filter" \| "list-filter" \| "date-filter" \| "text" \| "image" \| "combo-chart-grouped-column-line" \| "combo-chart-stacked-column-line"` | | 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. | | `comp` | `string \| Type>> \| (new () => AgTypeScriptComponent>)` | | Custom component. Either: a `string` that matches a custom component in the studio `components` property; a custom Angular component; or a custom TypeScript component class (no Angular; working directly with the DOM). | | `defaultSize` | `AgWidgetSize` | | Default widget size when created. | | `minSize` | `AgWidgetSize` | | Minimum widget size constraints. | | `toolbar` | `(AgWidgetToolbarButton \| AgDefaultWidgetAction)[]` | `['duplicate', 'delete']` | 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. | | `featureConfig` | `AgWidgetFeatureConfig` | | Optional feature configuration. | | `options` | `TOptions` | | Optional options passed directly to widget. | | `ai` | `AgWidgetAiMetadata` | | Optional structured AI metadata for this widget type. | Custom widgets are provided to the `widgets` property, similar to the [Available Widgets](https://www.ag-grid.com/studio/archive/3.0.0/angular/widget-configuration/#available-widgets) configuration. Provide the custom widget definitions to the `createWidgets(params)` helper function, and add them to the menu. Import `createWidgets` from `ag-studio-angular` rather than `ag-studio`, so that the Angular-specific widget defaults are applied. ```ts this.widgets = (widgetConfig) => createWidgets({ 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](https://www.ag-grid.com/studio/archive/3.0.0/angular/registry-type/). ```ts interface CustomRegistry extends AgBaseRegistry { widgets: readonly (AgDefaultWidgetDefinition | CustomWidgetDefinition)[] } ``` ### Form 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 Configuration](https://www.ag-grid.com/studio/archive/3.0.0/angular/custom-widgets-form/) page for more details. ### AI Integration For a custom widget to work with [AI](https://www.ag-grid.com/studio/archive/3.0.0/angular/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. ## Data Mapping 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: ```ts 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.', }, }; ``` A widget does not have to rely on a data mapping to choose its fields. See [Reading the Report Schema](https://www.ag-grid.com/studio/archive/3.0.0/angular/custom-widgets/#reading-the-report-schema). ## Widget Component The custom component is an Angular component that implements the `AgCustomComponent` interface. | Property | Type | Default | Description | | --- | --- | --- | --- | | `agInit` | `Function` | | Called once on initialisation with params for rendering this component. | | `refresh` | `Function` | | Called for every subsequent params update. | The `agInit` and `refresh` methods receive params of type `AgWidgetParams`. ### Custom Widget Params | Property | Type | Default | Description | | --- | --- | --- | --- | | `api` | [`AgStudioApi`](https://www.ag-grid.com/studio/archive/3.0.0/angular/studio-api/) | | Studio API. | | `context` | `TContext` | | Application context as set on `context` Studio property. | | `widgetId` | `string` | | Widget ID. | | `widgetType` | `string` | | Widget type. | | `format` | `TWidget["format"]` | | Widget format as constructed from the widget form. | | `dataMapping` | `AgWidgetDataMapping` | | Widget data mapping values. | | `sort` | `AgWidgetSort[] \| undefined` | | Widget sort if defined. | | `config` | `AgWidgetConfig` | | Widget configuration. | | `widgetApi` | `AgWidgetApi` | | Widget API. Provides access to retrieve data. | ### Display State 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. ```ts widgetApi.setDisplayState('loading'); const response = await widgetApi.getData(request); // ... process the response widgetApi.setDisplayState('displayed'); ``` ### Loading Data Data is loaded via `widgetApi.getData(request)`. The request can be constructed from the data mapping values in the params. | Property | Type | Default | Description | | --- | --- | --- | --- | | `kind` | `"flat"` | | Flat row query. Omit for backwards compatibility. | | `fields` | `AgWidgetField[]` | | List of fields to return in the query. Unaggregated fields will automatically be used for grouping. | | `sort` | `AgSort[]` | | Sort the result based on the provided fields. | | `filter` | `AgFilter[]` | | Additional filter to apply. Page-level filters and widget-level filters (including from filter widgets and cross filters) will be automatically applied. | | `limit` | `AgLimit` | | Limit the number of rows returned, or for pagination. | If the widget is making multiple independent data requests, then pass a second options argument to `getData(request, options)` where options contains a distinct query ID per request (e.g. `{ queryId: 'request1' }`). Otherwise the later requests will cancel the earlier requests. If your widget only makes one data request (per call to `refresh`), this is not required. ### Reading the Report Schema A widget does not have to rely on a data mapping to choose its fields. Call `getSchema()` on the widget API to list every table and field in the report's schema. Tables, and the fields within each table, come back in the order the data panel lists them. The example below defines a widget with no data mapping. It reads the schema, then shows a grid with one column per field. #### Schema Widget ```ts import '@angular/compiler'; import { provideHttpClient } from '@angular/common/http'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component.ts'; const app = bootstrapApplication(AppComponent, { providers: [provideHttpClient()], }); ``` [Live example: Schema Widget](https://www.ag-grid.com/studio/archive/3.0.0/examples/custom-widgets/schema-widget/angular/) ### Popups 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. ## Cross-Filtering #### Custom Widget with Cross Filter ```ts import '@angular/compiler'; import { provideHttpClient } from '@angular/common/http'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component.ts'; const app = bootstrapApplication(AppComponent, { providers: [provideHttpClient()], }); ``` [Live example: Custom Widget with Cross Filter](https://www.ag-grid.com/studio/archive/3.0.0/examples/custom-widgets/cross-filter-widget/angular/) To implement cross-filtering from within a custom widget, the cross filter methods can be used from the widget API. | Property | Type | Default | Description | | --- | --- | --- | --- | | `toggleCrossFilter` | `Function` | | Set a cross filter. | | `resetCrossFilter` | `Function` | | Clear cross filter. | | `getCrossFilterSelections` | `Function` | | Get the current cross filter for this widget. | Every selection belongs to a `group`, a zero-based number identifying which of the widget's selections is being set. A widget holds one selection per group, and selections in different groups are independent of each other. A widget that holds a single selection should pass `group: 0`; a widget that selects on several fields at once should give each field its own group. A widget that selects on several fields *together* - a sankey link or a matrix cell, where one click means "this channel **and** this product" - should use a multi value selection instead of a group per field. Each `toggleCrossFilter` call with `type: 'multiValue'` contributes one combination of field and value pairs; the pairs within a combination must all match, and a row is included when it matches any one of the combinations the selection holds. Toggling the same set of pairs again removes that combination. ```ts api.toggleCrossFilter({ type: 'multiValue', values: [ { field: channelField, value: 'Online' }, { field: productField, value: 'Clothing' }, ], group: 0, }); ``` To support the cross filter highlight behaviour (similar to some of the default charts, e.g. column charts), enable it in the widget definition. ```ts 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`). ## AG Grid & AG Charts in Widgets 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): ```ts const chartOptions = { // ... other options theme: getChartTheme(api), background: { fill: 'transparent' } }; ``` > **Note** > > Using AG Grid Enterprise or AG Charts Enterprise in a custom widget requires the relevant AG Grid Enterprise or AG Charts Enterprise licence. ## Custom Widget Examples ### Sankey Chart A Sankey diagram visualises flow between two sets of nodes, sized by a numeric measure. This example maps a sales dataset (channel → product category) alongside a bar chart of the same revenue measure. #### Custom Widget: Sankey ```ts import '@angular/compiler'; import { provideHttpClient } from '@angular/common/http'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component.ts'; const app = bootstrapApplication(AppComponent, { providers: [provideHttpClient()], }); ``` [Live example: Custom Widget: Sankey](https://www.ag-grid.com/studio/archive/3.0.0/examples/custom-widgets/sankey-widget/angular/) The widget takes no part in cross filtering: it requests its data with `crossFilter: 'none'`, so the flow diagram always covers the whole dataset and its node set never reflows. For a custom widget that does cross filter, see the Custom Widget with Cross Filter example above. ### Choropleth Map 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. #### Custom Widget: Choropleth Map ```ts import '@angular/compiler'; import { provideHttpClient } from '@angular/common/http'; import { bootstrapApplication } from '@angular/platform-browser'; import { AppComponent } from './app.component.ts'; const app = bootstrapApplication(AppComponent, { providers: [provideHttpClient()], }); ``` [Live example: Custom Widget: Choropleth Map](https://www.ag-grid.com/studio/archive/3.0.0/examples/custom-widgets/map-widget/angular/) 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.