--- product: "AG Studio" title: "Widget Basics" description: "Add, move, resize and remove Widgets in an AG Studio report, create a Table by dropping a field on the page, and understand why a Widget shows a loading, empty, incomplete or invalid state." framework: react version: "3.1.0" related: - title: "Building Widgets" url: "https://www.ag-grid.com/studio/analysts/building-widgets/" - title: "Page Layout" url: "https://www.ag-grid.com/studio/analysts/page-layout/" - title: "AI Assistant" url: "https://www.ag-grid.com/studio/analysts/ai-assistant/" - title: "Exporting and Printing" url: "https://www.ag-grid.com/studio/analysts/exporting-and-printing/" llms: "https://www.ag-grid.com/studio/llms.txt" --- # Widget Basics Widgets are the visual building blocks of a report. You create them on the layout, then set up their data and appearance in the Compose Panel. ## Widget Creation The main way to create a Widget is to drag data or a Widget onto the page. You can also click a Widget icon in the Compose Panel to create that Widget on the page. Dropping a field from the Data Panel onto an empty part of the page creates a Table with that field in its Columns slot. To start with several fields, hold Ctrl (Cmd on a Mac) and click each field in the Data Panel, then drag them together. Your developer can change which Widget a dropped field creates. When you drag a Widget, it snaps to the [Layout Grid](https://www.ag-grid.com/studio/analysts/page-layout/#layout-grid) and a preview shows where it will be placed. If the Widget would extend beyond the layout, it is placed at the nearest valid position and size instead. Where possible, the Widget is resized to fit the available space. Once the Widget is created, you can resize it from its edges or corners, depending on the Widget. Resizing also snaps to the grid. Each Widget type has a minimum size, and resizing stops when the Widget reaches it. The example below shows an empty page in [Edit Mode](https://www.ag-grid.com/studio/analysts/user-interface/#modes). To create a Widget, drag one from the [Compose Panel](https://www.ag-grid.com/studio/analysts/user-interface/#compose-panel), or drag a field from the [Data Panel](https://www.ag-grid.com/studio/analysts/user-interface/#data-panel) onto the canvas. #### Widget Creation ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getMainDemoData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "a", }, ], selectedPageId: "a", }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, panels: { edit: { right: ["edit", "data"], }, }, data: getMainDemoData("https://www.ag-grid.com/studio/example-assets"), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Widget Creation](https://www.ag-grid.com/studio/examples/widget-basics/widget-creation/typescript/) ## Widget Types AG Studio provides Widgets for tables, charts, headline values, on-canvas filters and static content. The [Widget Catalogue](https://www.ag-grid.com/studio/analysts/widget-catalogue/) lists every Widget in the Widget selector, with its variants, the data it needs and the options specific to it. Once a Widget is on the layout, configure its slots and appearance in the Compose Panel. See [Building Widgets](https://www.ag-grid.com/studio/analysts/building-widgets/) for the Setup and Format tabs. ## Widget Toolbar When a Widget is focused, a toolbar appears with actions for working with it. By default, a focused Widget has a blue border around it. The available actions depend on the current [Mode](https://www.ag-grid.com/studio/analysts/user-interface/#modes) and the Widget type. For example, some actions are only available in Edit Mode, and different Widget types may show different menus. | Name | Icon | Mode | Description | | --- | --- | --- | --- | | **CSV** | ![CSV export](https://www.ag-grid.com/studio/_astro/csv.BdcV8hsI.svg) | Both | Exports the Widget data as a CSV file. | | **Download** | ![Download](https://www.ag-grid.com/studio/_astro/download.pMmiFmuU.svg) | Both | Downloads the chart as an image. | | **Duplicate** | ![Duplicate](https://www.ag-grid.com/studio/_astro/copy.-shW46oD.svg) | Edit | Creates a copy of the Widget. | | **Delete** | ![Delete](https://www.ag-grid.com/studio/_astro/delete.Bh1EBMgU.svg) | Edit | Removes the Widget from the layout. | Table, Pivot Table and Chart Widgets show a CSV button. Chart Widgets also show a Download button for saving the chart as an image, which the Table Widget does not have. An exported CSV is named after the Widget title, and its values are formatted just as they appear in the Widget. See [Exporting and Printing](https://www.ag-grid.com/studio/analysts/exporting-and-printing/) for details. ## Widget States A Widget shows its content once its data has loaded. While it loads, or when it cannot show content, it shows one of the states below instead. A loading Widget shows no other state. An invalid configuration takes priority over an empty state or an incomplete setup. ### Loading A Widget shows a loading icon while it fetches its data. When the Widget is wide enough, the text "Loading..." appears beside the icon. A Widget fetches data when the page opens, and again when its fields, its filters or its data change. The first time a Widget loads, the loading state covers the whole Widget. When a Widget that already shows data refreshes, its current content stays visible behind the loading icon until the new data arrives. A fast load shows no loading state, so quick refreshes do not flicker. ### Empty State A Widget shows "No data to display" when it has the fields it needs but nothing to show. The common causes are: - The filters applied to the Widget match no rows. These include [Page and Widget Filters](https://www.ag-grid.com/studio/analysts/page-and-widget-filters/) and selections made in other Widgets with [Cross-Filtering](https://www.ag-grid.com/studio/analysts/cross-filtering/). - The fields in the Widget have no values, or only blank values. - The data could not be loaded, for example because the data source failed or did not respond. Ask your developer if a Widget shows no data where you expect some. - In View Mode, the Widget's setup is incomplete. See [Incomplete Setup](https://www.ag-grid.com/studio/analysts/widget-basics/#incomplete-setup). Each Widget type has its own rule for when it has nothing to show: | Widget | Shows "No data to display" when | | --- | --- | | Charts | The data has no rows to plot. | | Table | The data has no rows. A Table also shows this state when the data source does not give each row a unique identity. Your developer needs to fix this. | | Pivot Table | The data has no rows. | | KPI | The value is blank and, when Sparkline X-Axis has a field, no point on the sparkline has a value. | | Multi KPI | Every field in Values is blank. | | Radial Gauge, Linear Gauge | The value is blank. A Gauge also shows this state for a value below zero when Max is above Min, as on the default scale, and for a value above zero when Max is below Min. | | Button Filter, List Filter | The field has no values. | | Date Filter | Never. Once its Value slot has a field, it shows its date controls. | | Text | A field is mapped to Value and its value is blank. Without a field, the Text Widget shows its typed text. | | Image | No field is mapped and no URL is entered, the mapped field's value is blank or is not an image address, or the image fails to load. | The example below shows the same bar chart with a page-level filter applied that returns no matching data. The Filters Panel is open to show the active filter condition. #### Empty State ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getMainDemoData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "a", widgets: { "region-net-sales": { type: "bar-chart-grouped", dataMapping: { categoryKey: [{ id: "stores.region" }], valueKey: [{ id: "net_sales" }], }, format: { title: { enabled: true, text: "Net Sales by Region", }, }, }, }, widgetLayout: { "region-net-sales": { xTrack: 0, yTrack: 0, xSpan: 24, ySpan: 32, }, }, filter: { page: [ { field: { id: "stores.region" }, model: { operator: "equals", value: "ZZZZZ", }, }, ], }, }, ], selectedPageId: "a", }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, panels: { edit: { right: ["filters"], }, }, data: getMainDemoData("https://www.ag-grid.com/studio/example-assets"), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Empty State](https://www.ag-grid.com/studio/examples/widget-basics/empty-state/typescript/) ### Incomplete Setup A Widget's setup is incomplete while a slot it requires is empty. Each Widget's Setup table in the [Widget Catalogue](https://www.ag-grid.com/studio/analysts/widget-catalogue/) shows which of its slots are required. For example, a Table needs a field in Columns, a Pivot Table needs a field in Values, and a KPI or Gauge needs a field in Value. Text and Image Widgets have no required slots. In Edit Mode, a Widget with an incomplete setup shows its type and a list of its slots in place of its content. Each empty slot has an **Add Data** button. Click it to choose a field, or drag a field from the Data Panel onto the slot. A slot that already has fields shows the field name, or a count such as "2 values". In View Mode, the same Widget shows "No data to display". ### Invalid Configuration A Widget shows "Invalid configuration" when it uses a field or filter it can no longer apply. A field in a slot is invalid when: - The field is no longer in the data, for example because it was removed from the data source. - The field's aggregation is no longer available. - The slot no longer accepts the field, for example because the field's type has changed. A Widget filter is invalid when its field is invalid for one of these reasons, or when the filter can no longer be applied to its field. While a Widget filter is invalid, the Widget does not show any data, so it never shows rows that the filter would have removed. If a missing field returns to the data, the Widget recovers without any change. The message says what is wrong and offers a button to fix it: - "Invalid field in data section", with a **View data** button. This selects the Widget and opens the slot in the Compose Panel. - "Invalid widget filter applied", with a **View filters** button. This selects the Widget and opens the filter in the Filters Panel. A small Widget may not have room for the message and its buttons. Make the Widget larger to see them.