---
title: "Adding Widgets"
description: "Add charts, KPIs, and tables to a dashboard: browse the full widget catalog, reuse a widget you already built, or ask an AI agent."
section: "Widgets"
canonical: "https://banksync.io/docs/widgets/adding-widgets"
specs: ["dashboards"]
---

Widgets are the building blocks of a dashboard: each one is a chart, a KPI, a table, or another visual tied to your data. You add widgets from the **library**, which you open with the `]` key or the **Widgets** button in the editor toolbar. The library has four tabs, each a different way to get to the widget you want.

![The add-a-widget library panel open on the Widgets tab: a searchable catalog of widget kinds, each card showing a mini-preview of the chart, KPI, or table.](https://cdn.banksync.io/screenshots/dashboards/widget-library.62c8f2679a3bdb71.png "The widget library: a searchable catalog of every widget kind, each card leading with a preview.")

[![Add a KPI widget and choose its data](https://cdn.banksync.io/videos/add-a-widget.poster.2211514e07cb22f2.png)](https://cdn.banksync.io/videos/add-a-widget.c3bd9b5508bd6ecb.mp4)

[Watch: Add a KPI widget and choose its data](https://cdn.banksync.io/videos/add-a-widget.c3bd9b5508bd6ecb.mp4)

## The four library tabs

- **Widgets** — The full catalog of widget kinds: every chart type plus KPI, table, text, image, embed, filter,
  action, and custom. Search it, preview each card, and click or drag to add a fresh widget.
- **Dashboard** — The widgets already on this dashboard, in one place. Edit one (opens the inspector) or remove it
  from the dashboard.
- **Workspace** — Every widget you have already built. Reuse one across dashboards without rebuilding it.
- **Packages** — Portable custom-widget packages available to your workspace. Choose one, pick its data, and
  install it.

A quick gloss of the terms that come up below: a widget is **pinned** to a dashboard (it appears there, but the underlying widget is shared, not copied); the **inspector** is the settings panel that opens when you select a widget; and to **detach** a widget is to remove it from one dashboard without deleting it.

> **Another way: ask an AI agent:** 'Penny, the in-app assistant, or an external AI agent (for example Claude using the BankSync MCP tools) can create dashboards, widgets, queries, and folders for you. See Building dashboards with an AI agent.'

## Browsing the catalog

The **Widgets** tab is where most widgets start. It lists every widget kind, with a search box at the top and a row of category chips under it: **All**, **Charts**, **Native**, **Visuals**, **Content**, **Controls**, and **Custom** (on Home, **Native** comes first). Type to narrow the list (for example "donut" or "table"), then add the one you want.

Each card is a tile that leads with a preview:

- **Charts, KPIs, tables, and text notes** draw a real sample with the same renderer your dashboard uses.
- **Native BankSync widgets** (such as account balances or feed activity) show a preview of the widget itself.
- **Images, embeds, filters, actions, and custom widgets** show an illustration of what they look like on a dashboard.

Under the preview, the card shows the kind's icon beside its name and a one-line description. A few cards also carry a badge:

| Badge          | Meaning                                                                                                   |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| **Soon**       | Not ready yet. The card is visible so you know it is coming, but it cannot be added.                      |
| **Beta**       | Works, but still maturing. Custom widgets carry this badge.                                               |
| **Needs data** | Your workspace has no data source yet. You can still add the widget; it waits until you connect a source. |

For more room, click **Browse all** at the top of the library, or open the catalog from the Widgets page. It shows the same cards with bigger previews under **Create**, **Saved**, and **Packages** tabs. Cards sit in a responsive grid: two per row in the library panel and on a phone, and three or four per row in the wider catalog.

**Add a widget from the catalog**

1. **Open the library** — Press the bracket key, or click Widgets in the toolbar.
2. **Find a kind** — Stay on the Widgets tab and scroll, pick a category chip, or type a word like "kpi" or "bar" to
   filter.
3. **Preview it** — Every card leads with a preview. Chart, KPI, table and note cards are drawn from sample rows by
   the same renderer your dashboard uses; the preview is illustrative, not your data.
4. **Add it** — Click the card to drop it at the next open spot, or drag it onto the canvas to place it
   precisely.

> **Worked example: spending by category:** 'Open the library with ], type "bar" on the Widgets tab, and add a bar chart. Then select it to open the inspector, point it at a feed, group by category, and sum the amount. Drag a corner to make it wider. To change anything later (the grouping, the chart kind, the colors), adjust it in the inspector. See Binding data for the field-by-field details.'

Whatever kind you start from, you can switch it in the inspector after placing it. Every chart kind in the catalog can be added and connected to your data, including the less common ones (funnel, waffle, polar, bubble, heatmap, treemap, radar, box plot, sankey, sunburst, and similar). Each gives you a field editor for picking the columns it needs. For a hierarchy chart such as a treemap or sunburst, **+ Add level** adds the next column you have not used yet.

## What happens after you add a data widget

BankSync prepares the widget against the sources you can actually access before it creates a runnable query and widget:

- With one compatible source and one valid field mapping, it completes setup and shows **Using the source name · Change**. The editor's Undo action can remove the new widget.
- With several compatible sources, it places the widget unconnected rather than picking for you. Its cell reads **No data source connected yet** with a **Choose data** action; the **Data** tab suggests the closest matches and lets you browse every bank, feed, and table in the workspace.
- With ambiguous fields, it asks which real fields should fill the widget's roles. It does not guess transaction-shaped names for a custom table.
- With no sources at all, the cell offers **Connect bank**, **Create table**, and **Create feed**, and reopens the same widget after a connection detour.
- If source inventory is temporarily unavailable, it says so and offers Retry. It does not misreport an outage as an empty workspace.

An unconnected widget owns no fake query, placeholder feed, or sample financial rows. It is a full widget — move, rename, duplicate, or delete it like any other — and safe to leave on an active dashboard while you design. It must be connected or removed before the dashboard can be published.

![The chart-kind picker showing the full catalog (line, area, bar, donut, pie, treemap, boxplot, heatmap, gauge, KPI, table and more) grouped by family, with a search box.](https://cdn.banksync.io/screenshots/dashboards/chart-kind-picker.d737c901e47cb93d.png "Starting a brand-new dashboard, the chart-kind picker offers the same catalog grouped by family.")

Gauge, meter, and progress are **chart kinds** (the "single value" family), so you find them in the catalog alongside line, bar, and the rest.

## Placing a widget: click or drag

This works the same way no matter which tab you added from. Clicking a library entry adds the widget at the next open spot on the grid. To place it precisely, **drag** it from the library onto the canvas: a ghost outline shows where it will land before you drop it. Once placed, drag the widget to move it and drag an edge to resize. The layout saves automatically.

On a brand-new, empty dashboard you do not even need to open the library first: the canvas shows an **Add a widget** prompt that opens the same chooser.

![An empty dashboard canvas with a launch card and an 'Add a widget' button, the on-canvas prompt that opens the widget chooser on a brand-new dashboard.](https://cdn.banksync.io/screenshots/dashboards/empty-canvas.fbb0afc37d0b7f13.png "On a new dashboard, the empty canvas itself prompts you to add your first widget.")

![A single widget placed and fully rendered in its cell on the dashboard grid, sitting in an open spot alongside the surrounding layout.](https://cdn.banksync.io/screenshots/dashboards/widget-cell.a227aeaf3625bf66.png "A widget settled into place on the grid after being dropped.")

## Reusing a widget you already built

The **Workspace** tab lists every widget in your workspace, each with a live preview. Adding one from here **pins** it onto the current dashboard rather than making a copy: it is the same widget, shown in more than one place. A small counter on each card shows how many dashboards use it (hover it for "Used on 3 dashboards"), and widgets already on this dashboard offer **Edit** and **Add another placement** instead of **Add**.

When you select a widget that is used on more than one dashboard, the inspector says so: "Used on 3 dashboards. Changes apply here only." Your edits then apply to this dashboard only: the first one turns this placement into its own copy, named "… (local)", and the other dashboards keep the original. Click **Change everywhere** before editing to update every dashboard instead. A widget used on just one dashboard shows no notice and saves in place.

> **Pinning is not copying:** 'Adding from Workspace pins the existing widget. From a dashboard, edits to a shared widget stay on that dashboard unless you choose Change everywhere. To change the shared widget for every dashboard at once, edit it from the Widgets page.'

## More than charts

Not every widget is a chart. The **Widgets** tab lists every kind, charts and non-charts alike. Search or scroll to find these:

- **KPI** — A single big number with an optional comparison and sparkline.
- **Table** — A formatted, paginated table of rows. Each column can be styled per its meaning: currency,
  percent, status pills, progress bars, mini sparklines, ratings, chips, links, and more.
- **Text** — A Markdown note for headings, context, or instructions.
- **Image & Embed** — A static image or an embedded external page.
- **Filter & Action** — A filter control, or a button that runs a workspace action.
- **Custom widget** — For developers: author your own widget in TypeScript against the BankSync widget SDK.

The catalog also has a **Layered chart** (a combo of bars, lines, and areas on one set of axes) and a **Divider** for section headings and spacing; see [Layout & composition widgets](/docs/widgets/dashboards-layout-widgets). **Stat grid**, **Tabs**, and the text, number, and date inputs are marked **Soon** and cannot be added yet.

> **Tables are richly formatted:** A table is not just plain text. Pick a format per column so each value reads the way a finance reader expects: amounts as currency, rates as percentages, states as colored status pills, completion as a progress bar, a trend as a tiny inline sparkline, plus dates, durations, ratings, chips, links, and images. Set this up in the table's column manager in the inspector. See KPI, table & gauge widgets for the full list.

## Removing a widget from a dashboard

There are two ways to take a widget off a dashboard, and both ask you to confirm:

- From the **Dashboard** tab of the library, find the widget and click its **trash** icon.
- Or **select the widget** on the canvas (its settings open in the inspector) and click **✕ Remove from dashboard** at the bottom of the inspector.

Either way this detaches it from **this** dashboard only: the widget stays in your library, so any other dashboard that pins it is unaffected and you can re-add it later.

![The widget inspector with the Info tab selected, description and empty-state controls, and a pinned footer button reading 'Remove from dashboard'.](https://cdn.banksync.io/screenshots/dashboards/inspector-shell.98c18ef335da0c30.png "The Remove from dashboard button lives at the bottom of the inspector, below the tabs.")

## Related guides

- [Binding data](/docs/widgets/binding-data): point a widget at a feed and choose what to group by and measure.
- [The chart kind catalog](/docs/widgets/chart-kinds): every chart kind and when to use it.
- [KPI, table & gauge widgets](/docs/widgets/kpi-table-gauge): configure the non-chart widget types, including a table's per-column formats.
- [Templates](/docs/dashboards/dashboard-templates): the portable way to reuse a widget or a whole dashboard layout across workspaces.
- [Publishing and sharing](/docs/dashboards/publishing-and-sharing): share a widget or dashboard with people outside the editor.

[Bind a widget to your data](/docs/widgets/binding-data)