# Widgets

> What a dashboard widget can chart: events, measures, breakdowns, filters, chart types and date range limits.

Source: https://docs.grovs.io/docs/analytics/dashboards/widgets

A widget is one chart on a [board](https://docs.grovs.io/docs/analytics/dashboards).

- **Metric** widgets chart one number: an event, how to count it, how to split it and what to filter.
- **Library** widgets add a ready-made panel from the built-in boards.

## Add a widget

### 1. Open the widget dialog

On one of your boards, click **Add widget**.

### 2. Name it

Enter a **Title**, for example `Installs by country`.

### 3. Choose what to show

On the **Metric** tab, under **Show**, pick an event and a **Measure**.

### 4. Filter and split it (optional)

Add filters under **Filter**. Under **Break down by**, pick a dimension and how many top values to keep.

### 5. Pick the chart

Choose a chart type, a size, and whether to compare with the previous period. The preview updates as you go.

### 6. Save

Click **Add widget**.

To change a widget, choose **Edit** from its actions menu, then click **Save widget**.

## What you can show

**Show** combines an event with a measure. **Unique visitors** counts distinct visitors; **Unique devices** counts distinct devices.

| Event                    | **Count**                                    | **Unique visitors** / **Unique devices** |
| ------------------------ | -------------------------------------------- | ---------------------------------------- |
| **Any event**            | All events, purchases included               | Yes                                      |
| **Install**              | App installs                                 | Yes                                      |
| **App open**             | App opens                                    | Yes                                      |
| **Link view**            | Link views                                   | Yes                                      |
| **Link open**            | App opens from a link                        | Yes                                      |
| **Reinstall**            | Reinstalls                                   | Yes                                      |
| **Referred user**        | Users who installed through a referral       | Yes                                      |
| **Link view (via link)** | Views that came through one of your links    | Count only                               |
| **Link-driven install**  | Installs that came through one of your links | Count only                               |
| A custom event name      | That event                                   | Yes                                      |

## Break down by

A breakdown splits the number by one dimension and keeps the top 1 to 50 values (10 by default). The rest are grouped as **Other**.

Dimensions: **Country**, **Platform**, **Source**, **Campaign**, **Link**, **App version**, **OS**, **OS version**, **Device**, **City**, **Event name**, **Screen**, **UTM source**, **UTM medium**, **UTM campaign**, **Ads platform**, **Language**, and any event property.

## Filters

Each filter has a field, an operator (`is`, `is not` or `contains`) and one or more values. A widget holds up to 25 filters, each with up to 50 values of up to 200 characters.

Filterable fields match the events explorer: event type and name, screen, platform, app version, country, city, language, device model, OS and OS version, UTM source, medium and campaign, ads platform, source, link, campaign, user identifier, session, visitor, event properties and user attributes.

## Chart types and sizes

| Chart        | Best for                                                    |
| ------------ | ----------------------------------------------------------- |
| **Number**   | One total, optionally against the previous period           |
| **Bar list** | Top values of a breakdown                                   |
| **Timeline** | Change over time, in the board's day, week or month buckets |
| **Table**    | A breakdown with exact numbers                              |

Sizes are **Small**, **Medium** and **Full width**.

**Compare** adds the previous period: a range of the same length ending the day before the board's start date. It cannot reach past your data retention. Timelines do not offer it.

## Ready-made panels

The **Library** tab adds a panel from the built-in boards: **New users trend**, **Acquisition channels**, **Top links**, **Top campaigns**, **Acquisition**, **Engagement**, **Revenue**, **Retention**, **Acquisition KPIs**, **Engagement KPIs**, **Revenue KPIs**, **Link KPIs** and **Revenue trend**.

Panels follow the board's date range and platform filter. Revenue panels need [revenue tracking](https://docs.grovs.io/docs/revenue).

## Date range limits

How far back a widget can read depends on how Grovs answers it.

| How the widget is answered                                                                    | Longest date range         |
| --------------------------------------------------------------------------------------------- | -------------------------- |
| From daily totals                                                                             | Your plan's data retention |
| From raw events, counting events                                                              | 366 days                   |
| From raw events, counting unique visitors or devices, or with a `contains` or `is not` filter | 90 days                    |

Simple widgets read daily totals, for example installs over time, by platform or by country. A widget reads raw events when it:

- has a filter other than a single platform
- counts **Any event**, a custom event or a link-only event
- uses a less common breakdown

`contains` and `is not` filters also only reach the recent part of your data retention. A widget over a limit shows an error instead of a chart, such as "Date range cannot exceed 90 days for this query". Narrow the board's date range or remove the filter.

On self-hosted deployments, `ANALYTICS_MAX_AGGREGATE_RANGE_DAYS` (default 90) and `ANALYTICS_RAW_COUNTER_MAX_DAYS` (default 366) set the two raw limits.

## What widgets cannot do

- Filter by a [segment](https://docs.grovs.io/docs/analytics/segments).
- Chart revenue as a metric. Use the revenue panels instead.