--- title: "Upgrading to AG Studio 2" framework: vue version: "2.1.2" --- # Upgrading to AG Studio 2 New time intelligence, field customisation, keyboard, charting and theming features. ## What's New AG Studio 2 introduces: - [Calendars](https://www.ag-grid.com/studio/vue/calendars/) - Group and analyse data across time periods. - [Field Customisation](https://www.ag-grid.com/studio/vue/editable-fields/) - Configure field labels, formatting and behaviour. - [Keyboard Shortcuts](https://www.ag-grid.com/studio/vue/keyboard-shortcuts/) - Drive Studio from the keyboard in edit and view modes. - [Group by Legend](https://www.ag-grid.com/studio/vue/building-widgets#group-by-legend) - Use a field as a chart legend to create grouped series. - [Pre-Configured Widgets](https://www.ag-grid.com/studio/vue/widget-configuration#pre-configured-widgets) - Offer widgets that come ready-configured for users to add. - [AI Extensibility](https://www.ag-grid.com/studio/vue/ai-toolkit/) - Extend the AI assistant with custom tools. - [Theme Builder](https://www.ag-grid.com/studio/theme-builder/) - A visual tool for building and customising themes. These features introduce certain breaking changes, as listed below. ## Documentation [See AG Studio 2.0 Documentation](https://www.ag-grid.com/studio/archive/2.0.1) ## Supported Frameworks The minimum supported framework and TypeScript versions have increased in AG Studio 2. See [Version Compatibility](https://www.ag-grid.com/studio/vue/compatibility/) for the full compatibility matrix. The minimum supported TypeScript version is now `5.8.3`. ## Dependencies Studio now requires an additional first-party dependency `ag-stack`. This is automatically included in the `ag-studio` package dependencies. ## Breaking Changes The full list of breaking changes in AG Studio 2. ### Fields / Formats The following properties have been updated on the field (`AgFieldDefinition`) and format (`AgFormatDefinition`): - `options` has been renamed to `formatOptions`. - `valueFormatter` has been removed and replaced with `createValueFormatter`. `createValueFormatter` should return a value formatting function. Note that `createValueFormatter` receives the full set of params (options, fields, API, context), but the value formatting function will only receive the value to be formatted. The format generic `TFormats` has now been replaced with `TRegistry`, with the custom format definition moved into the [Registry Type](https://www.ag-grid.com/studio/vue/registry-type/) (`AgBaseRegistry` gains the `formats` property). The following have had the generic property changed: `AgDataSourcesDefinition` (now only `TRegistry` generic), `AgExpressionFieldDefinition` (`TRegistry` swapped with `TExpressionOperatorTypes` and `TFormats` removed), `AgExpressionOperatorTypes`, `AgFunctionExpression`, `AgExpression`, `AgSimpleDataSourceDefinition` (generic order changed), `AgAsyncTableDefinition`, `AgDataSourceDefinition`, `AgDataSource`, `AgDataSourcesUpdate`, `AgFieldDefinition` (generic order changed), `AgFormatOverride` (added as first generic) and `createFormats`. ### Filters The date-specific filter operators have been removed in favour of their generic equivalents: | Removed (date-specific) | Replacement (generic) | | --- | --- | | `on` | `equals` | | `notOn` | `notEqual` | | `after` | `greaterThan` | | `onOrAfter` | `greaterThanOrEqual` | | `before` | `lessThan` | | `onOrBefore` | `lessThanOrEqual` | | `inRange` | `between` | The `between` operator (formerly `inRange`) is now **inclusive** of its endpoints, where it was previously exclusive. For the previous exclusive behaviour, combine `greaterThan` and `lessThan` with an `AND`. Saved filter state from a version prior to `2.0.0` is migrated to the new operator names automatically on load. You only need to update code that sets these operators directly. The filter state types now take the [Registry Type](https://www.ag-grid.com/studio/vue/registry-type/) instead of the removed `AgFilterOperatorTypes`: - The types `AgFilterOperatorTypeDefinition` and `AgFilterOperatorTypes` have been removed. - Types that previously took `AgFilterOperatorTypes` as a generic now take the registry type instead. Pass `TRegistry`, use the default `AgDefaultRegistry`, or pass your own registry type. - Where `TRegistry` has been added as a generic (or replaced), it has been added as the **first** generic, shifting existing generics to the right. - Types which had `AgFilterOperatorTypes` as a generic (but not the first), and now have `TRegistry` as the first: `AgConditionDefinition`, `AgLogicalDefinition`, `AgFilterDefinition`, `AgConditionFilterState`, `AgLogicalFilterState`, `AgFilterModelState`, `AgFilterState`, `AgFiltersState`. - Types which did not have `AgFilterOperatorTypes` as a generic, and now have `TRegistry` as the first: `AgFilterCondition`, `AgFilterLogical`, `AgFilter`. ### Removed APIs - `AgRequestOptions.preferredShape` has been removed. Use `AgRequestOptions.shape` instead. - The `AgWidget` interface has been removed. Use `AgDefaultWidget` instead. - `AgWidgetConfig.crossFilter` has been removed. Use `AgWidgetConfig.featureConfig?.crossFilter` instead. - The deprecated locale keys `aiToolAddWidgetsDesc`, `aiToolConfigurePageFiltersDesc`, `aiToolConfigureWidgetFiltersDesc`, `aiToolAddWidgets`, `aiToolConfigurePageFilters` and `aiToolConfigureWidgetFilters` have been removed. ### Theming - `chartAxisColor` has been renamed `chartAxisLineColor`. - `chartSeparationLinesColor` has been renamed `chartGroupedCategoryLineColor`. - `createStudioTheme()` no longer includes the default Studio icons. They are now exported as the part `iconSetStudio`. `createStudioTheme().withPart(iconSetStudio)` reproduces the previous behaviour. The default theme and `studioTheme` are unchanged. - Studio elements are now inserted into application-owned DOM with a consistent structure: `application-div > div.ag-theme-x > div.ag-ltr > div.ag-some-component`. The theme and RTL classes that were previously set directly on a component are now set on a parent element. Application CSS targeting these classes on the component itself must be updated - for example, `.ag-studio-root-inner.ag-rtl { ... }` becomes `.ag-rtl .ag-studio-root-inner { ... }`. ### Widgets & Toolbar - `AgWidgetConfig` now takes the widget shape as its **first** generic: `AgWidgetConfig` becomes `AgWidgetConfig`. This corrects the typing of `AgWidgetConfig.data`. - The `AgWidgetConfig.toolbar` property has been removed. The toolbar is implemented by Studio, so custom widgets should not set it. - `featureConfig.exportCsv` has been removed from the widget definition (`AgBaseWidgetDefinition`). To disable CSV export for a Studio-provided widget, remove the item with id `'export'` from the widget definition's `toolbar` property instead. - The `id` property is now required for toolbar items (`AgWidgetToolbarItem` / `AgWidgetToolbarButton`) in a widget's `toolbar` definition. - The deprecated `overrides` Studio property has been removed. Use the `widgets` property to [Customise the Widget Configurations](https://www.ag-grid.com/studio/vue/widget-configuration#change-the-configuration-for-individual-widgets) and [Customise the Available Widgets](https://www.ag-grid.com/studio/vue/widget-configuration#customise-the-available-widgets), and the `page` property to [Customise the Page Setup Form](https://www.ag-grid.com/studio/vue/modes-layout#customising-panel-content). The `AgWidgetDisplayProperties` interface has been removed. - The callback form of the `widgets` Studio property now receives `AgWidgetsConfig` instead of `AgWidgetsConfig`, since it is passed the default widgets rather than the overridden ones. ## Behaviour Changes The full list of behaviour changes in AG Studio 2. - Date-time fields are now filtered using the full date and time rather than the date alone. Saved filter state against a date-time field may match different rows: - `greaterThan` now matches values later in the same day. - `lessThanOrEqual` no longer matches values in the same day, matching up to the previous day only. - `equals` no longer matches every value within the day. - Grand total row values in the grid widget are now displayed in bold. - When state is loaded in View Mode without a `widgetLayout` property, widgets are no longer added to the layout. - Series-specific format options are now grouped into a single section named after the series, located at the end of the Format panel. Options previously displayed under generic headings or split across multiple panel locations now appear together under their series name. This affects Bar, Column, Value, Linear Gauge, Radial Gauge, Text, Image, Table, Button Filter, List Filter, and Date Filter widgets: - The bar width option for Bar and Column charts has been moved into their respective series sections of the Format panel. - Value and gauge style options are consolidated under their respective series sections, with gauge scale options grouped as a sub-section. - Text and Image options previously shown under generic headings now appear under their respective series sections. - Filter widgets group all options under their respective series sections. Selection Type for List Filter and Filter Type for Date Filter are moved into Format.